[tor-commits] [tor/master] Module-level docs for ext_orport and router.c

[nickm at torproject.org]

commit 54fda6b98ad79d3c2ce50858cea2226675ebfd4c
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Oct 18 19:32:49 2016 -0400

    Module-level docs for ext_orport and router.c
---
 src/or/ext_orport.c | 12 +++++++++++-
 src/or/router.c     | 19 +++++++++++++++++--
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/or/ext_orport.c b/src/or/ext_orport.c
index fb7add1..676adfd 100644
--- a/src/or/ext_orport.c
+++ b/src/or/ext_orport.c
@@ -4,7 +4,17 @@
 /**
  * \file ext_orport.c
  * \brief Code implementing the Extended ORPort.
-*/
+ *
+ * The Extended ORPort interface is used by pluggable transports to
+ * communicate additional information to a Tor bridge, including
+ * address information. For more information on this interface,
+ * see pt-spec.txt in torspec.git.
+ *
+ * There is no separate structure for extended ORPort connections; they use
+ * or_connection_t objects, and share most of their implementation with
+ * connection_or.c.  Once the handshake is done, an extended ORPort connection
+ * turns into a regular OR connection, using connection_ext_or_transition().
+ */
 
 #define EXT_ORPORT_PRIVATE
 #include "or.h"
diff --git a/src/or/router.c b/src/or/router.c
index 1ac8351..10498e8 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -37,8 +37,23 @@
 
 /**
  * \file router.c
- * \brief OR functionality, including key maintenance, generating
- * and uploading server descriptors, retrying OR connections.
+ * \brief Miscellaneous relay functionality, including RSA key maintenance,
+ * generating and uploading server descriptors, picking an address to
+ * advertise, and so on.
+ *
+ * This module handles the job of deciding whether we are a Tor relay, and if
+ * so what kind. (Mostly through functions like server_mode() that inspect an
+ * or_options_t, but in some cases based on our own capabilities, such as when
+ * we are deciding whether to be a directory cache in
+ * router_has_bandwidth_to_be_dirserver().)
+ *
+ * Also in this module are the functions to generate our own routerinfo_t and
+ * extrainfo_t, and to encode those to signed strings for upload to the
+ * directory authorities.
+ *
+ * This module also handles key maintenance for RSA and Curve25519-ntor keys,
+ * and for our TLS context. (These functions should eventually move to
+ * routerkeys.c along with the code that handles Ed25519 keys now.)
  **/
 
 /************************************************************/