commit 1332d3b6fa4faa2ef961d1057044fb4cd2608257 Author: Nick Mathewson nickm@torproject.org Date: Mon Oct 14 15:53:04 2019 -0400

doc/HACKING/design: address comments from ahf --- doc/HACKING/design/00-overview.md | 34 ++++++++++++++++---------------- doc/HACKING/design/01.00-lib-overview.md | 6 +++--- 2 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/doc/HACKING/design/00-overview.md b/doc/HACKING/design/00-overview.md index fde476dfa..ff40a566b 100644 --- a/doc/HACKING/design/00-overview.md +++ b/doc/HACKING/design/00-overview.md @@ -56,38 +56,38 @@ will be scheduled. The codebase is divided into a few top-level subdirectories, each of which contains several sub-modules.

- src/ext -- Code maintained elsewhere that we include in the Tor - source distribution. + * `src/ext` -- Code maintained elsewhere that we include in the Tor + source distribution.

- src/lib -- Lower-level utility code, not necessarily tor-specific. + * src/lib` -- Lower-level utility code, not necessarily tor-specific.

- src/trunnel -- Automatically generated code (from the Trunnel) - tool: used to parse and encode binary formats. + * `src/trunnel` -- Automatically generated code (from the Trunnel + tool): used to parse and encode binary formats.

- src/core -- Networking code that is implements the central parts of + * `src/core` -- Networking code that is implements the central parts of the Tor protocol and main loop.

- src/feature -- Aspects of Tor (like directory management, running a + * `src/feature` -- Aspects of Tor (like directory management, running a relay, running a directory authorities, managing a list of nodes, running and using onion services) that are built on top of the mainloop code.

- src/app -- Highest-level functionality; responsible for setting up - and configuring the Tor project, making sure all the lower-level + * `src/app` -- Highest-level functionality; responsible for setting up + and configuring the Tor daemon, making sure all the lower-level modules start up when required, and so on.

- src/tools -- Binaries other than Tor that we produce. Currently this + * `src/tools` -- Binaries other than Tor that we produce. Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper module.

- src/test -- unit tests, regression tests, and a few integration + * `src/test` -- unit tests, regression tests, and a few integration tests.

-In theory, the above parts of the codebase are sorted from highest-level -to lowest-level, where high-level code is only allowed to invoke -lower-level code, and lower-level code never includes or depends on code -of a higher level. In practice, this refactoring is incomplete: The -modules in src/lib are well-factored, but there are many "upward -dependencies" in src/core and src/feature. We aim to eliminate those +In theory, the above parts of the codebase are sorted from highest-level to +lowest-level, where high-level code is only allowed to invoke lower-level +code, and lower-level code never includes or depends on code of a higher +level. In practice, this refactoring is incomplete: The modules in `src/lib` +are well-factored, but there are many layer violations ("upward +dependencies") in `src/core` and `src/feature`. We aim to eliminate those over time.

### Some key high-level abstractions ### diff --git a/doc/HACKING/design/01.00-lib-overview.md b/doc/HACKING/design/01.00-lib-overview.md index 08dec51a0..58a92f406 100644 --- a/doc/HACKING/design/01.00-lib-overview.md +++ b/doc/HACKING/design/01.00-lib-overview.md @@ -85,9 +85,9 @@ level): code is specifically written to avoid having to log, because the logging module depends on it.

- * `lib/container` -- General purpose containers, including dynamic arrays, - hashtables, bit arrays, weak-reference-like "handles", bloom - filters, and a bit more. + * `lib/container` -- General purpose containers, including dynamic arrays + ("smartlists"), hashtables, bit arrays, weak-reference-like "handles", + bloom filters, and a bit more.

* `lib/trace` -- A general-purpose API for introducing function-tracing functionality into Tor. Currently not much used.