Make sure that every module in src/or has a brief description.

21 files changed, 126 insertions, 6 deletions

diff --git a/src/or/addressmap.c b/src/or/addressmap.c
index 9c29fb2acb..26b062f095 100644
--- a/src/or/addressmap.c
+++ b/src/or/addressmap.c
@@ -4,6 +4,15 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file addressmap.c
+ *
+ * \brief The addressmap module manages the processes by which we rewrite
+ * addresses in client requess.  It handles the MapAddress controller and
+ * torrc commands, and the TrackHostExits feature, and the client-side DNS
+ * cache (deprecated).
+ */
+
 #define ADDRESSMAP_PRIVATE
 
 #include "or.h"
diff --git a/src/or/buffers.c b/src/or/buffers.c
index cdb499b8da..9bd0cbac78 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -8,7 +8,8 @@
  * \file buffers.c
  * \brief Implements a generic interface buffer.  Buffers are
  * fairly opaque string holders that can read to or flush from:
- * memory, file descriptors, or TLS connections.
+ * memory, file descriptors, or TLS connections.  Buffers are implemented
+ * as linked lists of memory chunks.
  **/
 #define BUFFERS_PRIVATE
 #include "or.h"
diff --git a/src/or/channel.c b/src/or/channel.c
index 46e833854b..45ff501de6 100644
--- a/src/or/channel.c
+++ b/src/or/channel.c
@@ -3,7 +3,11 @@
 
 /**
  * \file channel.c
- * \brief OR-to-OR channel abstraction layer
+ *
+ * \brief OR/OP-to-OR channel abstraction layer. A channel's job is to
+ * transfer cells from Tor instance to Tor instance.
+ * Currently, there is only one implementation of the channel abstraction: in
+ * channeltls.c.
  **/
 
 /*
diff --git a/src/or/channeltls.c b/src/or/channeltls.c
index 016ef75456..67e6d40697 100644
--- a/src/or/channeltls.c
+++ b/src/or/channeltls.c
@@ -3,7 +3,9 @@
 
 /**
  * \file channeltls.c
- * \brief channel_t concrete subclass using or_connection_t
+ *
+ * \brief A concrete subclass of channel_t using or_connection_t to transfer
+ * cells between Tor instances.
  **/
 
 /*
diff --git a/src/or/circpathbias.c b/src/or/circpathbias.c
index a0115cc6ec..5c8849f8ce 100644
--- a/src/or/circpathbias.c
+++ b/src/or/circpathbias.c
@@ -4,6 +4,15 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file circpathbias.c
+ *
+ * \brief Code to track success/failure rates of circuits built through
+ * different tor nodes, in an attempt to detect attacks where
+ * an attacker deliberately causes circuits to fail until the client
+ * choses a path they like.
+ */
+
 #include "or.h"
 #include "channel.h"
 #include "circpathbias.h"
diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index daf0b2af0b..69c34b5f7b 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -6,7 +6,9 @@
 
 /**
  * \file circuitbuild.c
- * \brief The actual details of building circuits.
+ *
+ * \brief Implements the details of building circuits (by chosing paths,
+ * constructing/sending create/extend cells, and so on).
  **/
 
 #define CIRCUITBUILD_PRIVATE
diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c
index ade371d39f..61d2bb83f7 100644
--- a/src/or/circuitlist.c
+++ b/src/or/circuitlist.c
@@ -6,7 +6,8 @@
 
 /**
  * \file circuitlist.c
- * \brief Manage the global circuit list.
+ *
+ * \brief Manage the global circuit list, and looking up circuits within it.
  **/
 #define CIRCUITLIST_PRIVATE
 #include "or.h"
diff --git a/src/or/circuitstats.c b/src/or/circuitstats.c
index 3ced5afad5..74492442a7 100644
--- a/src/or/circuitstats.c
+++ b/src/or/circuitstats.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file circuitstats.c
+ *
+ * \brief Maintains and analyzes statistics about circuit built times, so we
+ * can tell how long we may need to wait for a fast circuit to be constructed.
+ */
+
 #define CIRCUITSTATS_PRIVATE
 
 #include "or.h"
diff --git a/src/or/confparse.c b/src/or/confparse.c
index ac21df25cb..26909c8fdb 100644
--- a/src/or/confparse.c
+++ b/src/or/confparse.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file confparse.c
+ *
+ * \brief Back-end for parsing and generating key-value files, used to
+ *   implement the torrc file format and the state file.
+ */
+
 #include "or.h"
 #include "confparse.h"
 #include "routerset.h"
diff --git a/src/or/dnsserv.c b/src/or/dnsserv.c
index ded0d8431b..941b9e20a6 100644
--- a/src/or/dnsserv.c
+++ b/src/or/dnsserv.c
@@ -2,7 +2,8 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file dnsserv.c \brief Implements client-side DNS proxy server code.  Note:
+ * \file dnsserv.c
+ * \brief Implements client-side DNS proxy server code.  Note:
  * this is the DNS Server code, not the Server DNS code.  Confused?  This code
  * runs on client-side, and acts as a DNS server.  The code in dns.c, on the
  * other hand, runs on Tor servers, and acts as a DNS client.
diff --git a/src/or/fp_pair.c b/src/or/fp_pair.c
index c863d4176c..a1924fea0e 100644
--- a/src/or/fp_pair.c
+++ b/src/or/fp_pair.c
@@ -1,6 +1,14 @@
 /* Copyright (c) 2013-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file fp_pair.c
+ *
+ * \brief Manages data structures for associating pairs of fingerprints. Used
+ * to handle combinations of identity/signing-key fingerprints for
+ * authorities.
+ **/
+
 #include "or.h"
 #include "fp_pair.h"
 
diff --git a/src/or/keypin.c b/src/or/keypin.c
index 574a76d51e..6c294c72e5 100644
--- a/src/or/keypin.c
+++ b/src/or/keypin.c
@@ -1,6 +1,13 @@
 /* Copyright (c) 2014, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file keypin.c
+ *
+ * \brief Functions and structures for associating routers' RSA key
+ * fingerprints with their ED25519 keys.
+ */
+
 #define KEYPIN_PRIVATE
 
 #include "orconfig.h"
diff --git a/src/or/microdesc.c b/src/or/microdesc.c
index 900a50eb41..520cadeea6 100644
--- a/src/or/microdesc.c
+++ b/src/or/microdesc.c
@@ -1,6 +1,13 @@
 /* Copyright (c) 2009-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file microdesc.c
+ *
+ * \brief Implements microdescriptors -- an abbreviated description of
+ *  less-frequently-changing router information.
+ */
+
 #include "or.h"
 #include "circuitbuild.h"
 #include "config.h"
diff --git a/src/or/nodelist.c b/src/or/nodelist.c
index 91353eea89..2fbcabb623 100644
--- a/src/or/nodelist.c
+++ b/src/or/nodelist.c
@@ -4,6 +4,14 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file nodelist.c
+ *
+ * \brief Structures and functions for tracking what we know about the routers
+ *   on the Tor network, and correlating information from networkstatus,
+ *   routerinfo, and microdescs.
+ */
+
 #include "or.h"
 #include "address.h"
 #include "config.h"
diff --git a/src/or/ntmain.c b/src/or/ntmain.c
index b31ed869d6..89739ad1b5 100644
--- a/src/or/ntmain.c
+++ b/src/or/ntmain.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ntmain.c
+ *
+ * \brief Entry points for running/configuring Tor as Windows Service.
+ */
+
 #ifdef _WIN32
 
 #include "or.h"
diff --git a/src/or/onion_ntor.c b/src/or/onion_ntor.c
index 539f06f61f..c39409608b 100644
--- a/src/or/onion_ntor.c
+++ b/src/or/onion_ntor.c
@@ -1,6 +1,12 @@
 /* Copyright (c) 2012-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file onion_ntor.c
+ *
+ * \brief Implementation for the ntor handshake.
+ */
+
 #include "orconfig.h"
 
 #define ONION_NTOR_PRIVATE
diff --git a/src/or/periodic.c b/src/or/periodic.c
index 109717f738..2f819e914f 100644
--- a/src/or/periodic.c
+++ b/src/or/periodic.c
@@ -1,6 +1,12 @@
 /* Copyright (c) 2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file periodic.c
+ *
+ * \brief Generic backend for handling periodic events.
+ */
+
 #include "or.h"
 #include "compat_libevent.h"
 #include "config.h"
diff --git a/src/or/routerkeys.c b/src/or/routerkeys.c
index 210178dc1d..9d3a9c3043 100644
--- a/src/or/routerkeys.c
+++ b/src/or/routerkeys.c
@@ -1,6 +1,14 @@
 /* Copyright (c) 2014, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file routerkeys.c
+ *
+ * \brief Functions and structures to handle generating and maintaining the
+ *  set of keypairs necessary to be an OR. (Some of the code in router.c
+ *  belongs here.)
+ */
+
 #include "or.h"
 #include "config.h"
 #include "router.h"
diff --git a/src/or/routerset.c b/src/or/routerset.c
index debe9ec6e1..073e762e13 100644
--- a/src/or/routerset.c
+++ b/src/or/routerset.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file routerset.c
+ *
+ * \brief Functions and structures to handle set-type selection of routers
+ *  by name, ID, address, etc.
+ */
+
 #define ROUTERSET_PRIVATE
 
 #include "or.h"
diff --git a/src/or/statefile.c b/src/or/statefile.c
index 7fe8dc5077..12cef12635 100644
--- a/src/or/statefile.c
+++ b/src/or/statefile.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file statefile.c
+ *
+ * \brief Handles parsing and encoding the persistent 'state' file that carries
+ *  miscellaneous persistent state between Tor invocations.
+ */
+
 #define STATEFILE_PRIVATE
 #include "or.h"
 #include "circuitstats.h"
diff --git a/src/or/torcert.c b/src/or/torcert.c
index ef5b4c0c3b..9c02f9c545 100644
--- a/src/or/torcert.c
+++ b/src/or/torcert.c
@@ -1,6 +1,13 @@
 /* Copyright (c) 2014, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file torcert.c
+ *
+ * \brief Implementation for ed25519-signed certificates as used in the Tor
+ * protocol.
+ */
+
 #include "crypto.h"
 #include "torcert.h"
 #include "ed25519_cert.h"