diff --git a/src/or/ext_orport.c b/src/or/ext_orport.c
index fb7add17d8ac554b6f7a9c77827fe9a94e83ba7b..676adfd8bfb19f2a194796346d0355bf12f6943a 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 1ac835147554416b35d84946f2b27898e1c30903..10498e8ae1c541a17112a9464a74b719bb0dcd0a 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.)
  **/
 
 /************************************************************/