[tor-commits] [tor/master] directory-level doxygen for "src/core"

Tue Nov 5 13:05:57 UTC 2019

commit e1cdca2e4f58c108539fe4c36205b16caca8d44f
Author: Nick Mathewson <nickm at torproject.org>
Date:   Mon Nov 4 16:28:28 2019 -0500

    directory-level doxygen for "src/core"
---
 doc/HACKING/design/03-modules.md    | 89 -------------------------------------
 src/core/core.dox                   | 12 +++++
 src/core/crypto/core_crypto.dox     |  6 ++-
 src/core/mainloop/core_mainloop.dox | 10 ++++-
 src/core/or/core_or.dox             | 62 +++++++++++++++++++++++++-
 src/core/proto/core_proto.dox       |  6 ++-
 6 files changed, 91 insertions(+), 94 deletions(-)

diff --git a/doc/HACKING/design/03-modules.md b/doc/HACKING/design/03-modules.md
index 93eb9d308..9ab2fa7da 100644
--- a/doc/HACKING/design/03-modules.md
+++ b/doc/HACKING/design/03-modules.md
@@ -1,95 +1,6 @@
 
 ## Tor's modules ##
 
-### Generic modules ###
-
-`buffers.c`
-: Implements the `buf_t` buffered data type for connections, and several
-low-level data handling functions to handle network protocols on it.
-
-`channel.c`
-: Generic channel implementation. Channels handle sending and receiving cells
-among tor nodes.
-
-`channeltls.c`
-: Channel implementation for TLS-based OR connections. Uses `connection_or.c`.
-
-`circuitbuild.c`
-: Code for constructing circuits and choosing their paths.  (*Note*:
-this module could plausibly be split into handling the client side,
-the server side, and the path generation aspects of circuit building.)
-
-`circuitlist.c`
-: Code for maintaining and navigating the global list of circuits.
-
-`circuitmux.c`
-: Generic circuitmux implementation. A circuitmux handles deciding, for a
-particular channel, which circuit should write next.
-
-`circuitmux_ewma.c`
-: A circuitmux implementation based on the EWMA (exponentially
-weighted moving average) algorithm.
-
-`circuituse.c`
-: Code to actually send and receive data on circuits.
-
-`command.c`
-: Handles incoming cells on channels.
-
-`config.c`
-: Parses options from torrc, and uses them to configure the rest of Tor.
-
-`confparse.c`
-: Generic torrc-style parser. Used to parse torrc and state files.
-
-`connection.c`
-: Generic and common connection tools, and implementation for the simpler
-connection types.
-
-`connection_edge.c`
-: Implementation for entry and exit connections.
-
-`connection_or.c`
-: Implementation for OR connections (the ones that send cells over TLS).
-
-`main.c`
-: Principal entry point, main loops, scheduled events, and network
-management for Tor.
-
-`ntmain.c`
-: Implements Tor as a Windows service. (Not very well.)
-
-`onion.c`
-: Generic code for generating and responding to CREATE and CREATED
-cells, and performing the appropriate onion handshakes. Also contains
-code to manage the server-side onion queue.
-
-`onion_fast.c`
-: Implements the old SHA1-based CREATE_FAST/CREATED_FAST circuit
-creation handshake. (Now deprecated.)
-
-`onion_ntor.c`
-: Implements the Curve25519-based NTOR circuit creation handshake.
-
-`onion_tap.c`
-: Implements the old RSA1024/DH1024-based TAP circuit creation handshake. (Now
-deprecated.)
-
-`relay.c`
-: Handles particular types of relay cells, and provides code to receive,
-encrypt, route, and interpret relay cells.
-
-`scheduler.c`
-: Decides which channel/circuit pair is ready to receive the next cell.
-
-`statefile.c`
-: Handles loading and storing Tor's state file.
-
-`tor_main.c`
-: Contains the actual `main()` function.  (This is placed in a separate
-file so that the unit tests can have their own `main()`.)
-
-
 ### Node-status modules ###
 
 `directory.c`
diff --git a/src/core/core.dox b/src/core/core.dox
index b37c5e2d8..11bf55cb7 100644
--- a/src/core/core.dox
+++ b/src/core/core.dox
@@ -5,4 +5,16 @@
 The "core" directory has the central protocols for Tor, which every
 client and relay must implement in order to perform onion routing.
 
+It is divided into three lower-level pieces:
+
+   - \refdir{core/crypto} -- Tor-specific cryptography.
+
+   - \refdir{core/proto} -- Protocol encoding/decoding.
+
+   - \refdir{core/mainloop} -- A connection-oriented asynchronous mainloop.
+
+and one high-level piece:
+
+   - \refdir{core/or} -- Implements onion routing itself.
+
 **/
diff --git a/src/core/crypto/core_crypto.dox b/src/core/crypto/core_crypto.dox
index 36c12371d..28ece92bb 100644
--- a/src/core/crypto/core_crypto.dox
+++ b/src/core/crypto/core_crypto.dox
@@ -1,4 +1,8 @@
 /**
 @dir /core/crypto
- at brief core/crypto
+ at brief core/crypto: Tor-specific cryptography
+
+This module implements Tor's circuit-construction crypto and Tor's
+relay crypto.
+
 **/
diff --git a/src/core/mainloop/core_mainloop.dox b/src/core/mainloop/core_mainloop.dox
index e97edde94..28cd42bf6 100644
--- a/src/core/mainloop/core_mainloop.dox
+++ b/src/core/mainloop/core_mainloop.dox
@@ -1,4 +1,12 @@
 /**
 @dir /core/mainloop
- at brief core/mainloop
+ at brief core/mainloop: Non-onion-routing mainloop functionality
+
+This module uses the event-loop code of \refdir{lib/evloop} to implement an
+asynchronous connection-oriented protocol handler.
+
+The layering here is imperfect: the code here was split from \refdir{core/or}
+without refactoring how the two modules call one another.  Probably many
+functions should be moved and refactored.
+
 **/
diff --git a/src/core/or/core_or.dox b/src/core/or/core_or.dox
index 754690e00..705e9b543 100644
--- a/src/core/or/core_or.dox
+++ b/src/core/or/core_or.dox
@@ -1,4 +1,62 @@
 /**
 @dir /core/or
- at brief core/or
-**/
+ at brief core/or: *Onion routing happens here*.
+
+This is the central part of Tor that handles the core tasks of onion routing:
+building circuit, handling circuits, attaching circuit to streams, moving
+data around, and so forth.
+
+Some aspects of this module should probably be refactored into others.
+
+Notable files here include:
+
+`channel.c`
+: Generic channel implementation. Channels handle sending and receiving cells
+among tor nodes.
+
+`channeltls.c`
+: Channel implementation for TLS-based OR connections. Uses `connection_or.c`.
+
+`circuitbuild.c`
+: Code for constructing circuits and choosing their paths.  (*Note*:
+this module could plausibly be split into handling the client side,
+the server side, and the path generation aspects of circuit building.)
+
+`circuitlist.c`
+: Code for maintaining and navigating the global list of circuits.
+
+`circuitmux.c`
+: Generic circuitmux implementation. A circuitmux handles deciding, for a
+particular channel, which circuit should write next.
+
+`circuitmux_ewma.c`
+: A circuitmux implementation based on the EWMA (exponentially
+weighted moving average) algorithm.
+
+`circuituse.c`
+: Code to actually send and receive data on circuits.
+
+`command.c`
+: Handles incoming cells on channels.
+
+`connection.c`
+: Generic and common connection tools, and implementation for the simpler
+connection types.
+
+`connection_edge.c`
+: Implementation for entry and exit connections.
+
+`connection_or.c`
+: Implementation for OR connections (the ones that send cells over TLS).
+
+`onion.c`
+: Generic code for generating and responding to CREATE and CREATED
+cells, and performing the appropriate onion handshakes. Also contains
+code to manage the server-side onion queue.
+
+`relay.c`
+: Handles particular types of relay cells, and provides code to receive,
+encrypt, route, and interpret relay cells.
+
+`scheduler.c`
+: Decides which channel/circuit pair is ready to receive the next cell.
diff --git a/src/core/proto/core_proto.dox b/src/core/proto/core_proto.dox
index 2e92a6513..13ce751a7 100644
--- a/src/core/proto/core_proto.dox
+++ b/src/core/proto/core_proto.dox
@@ -1,4 +1,8 @@
 /**
 @dir /core/proto
- at brief core/proto
+ at brief core/proto: Protocol encoding/decoding
+
+These functions should (but do not always) exist at a lower level than most
+of the rest of core.
+
 **/



