directory-level doxygen for "src/core"

5 files changed, 91 insertions, 5 deletions

diff --git a/src/core/core.dox b/src/core/core.dox
index b37c5e2d81..11bf55cb78 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 36c12371d9..28ece92bb8 100644
--- a/src/core/crypto/core_crypto.dox
+++ b/src/core/crypto/core_crypto.dox
@@ -1,4 +1,8 @@
 /**
 @dir /core/crypto
-@brief core/crypto
+@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 e97edde946..28cd42bf60 100644
--- a/src/core/mainloop/core_mainloop.dox
+++ b/src/core/mainloop/core_mainloop.dox
@@ -1,4 +1,12 @@
 /**
 @dir /core/mainloop
-@brief core/mainloop
+@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 754690e008..705e9b5436 100644
--- a/src/core/or/core_or.dox
+++ b/src/core/or/core_or.dox
@@ -1,4 +1,62 @@
 /**
 @dir /core/or
-@brief core/or
-**/
+@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 2e92a6513a..13ce751a76 100644
--- a/src/core/proto/core_proto.dox
+++ b/src/core/proto/core_proto.dox
@@ -1,4 +1,8 @@
 /**
 @dir /core/proto
-@brief core/proto
+@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.
+
 **/