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

diff --git a/src/or/addressmap.c b/src/or/addressmap.c
index 9c29fb2acb51e07c7ddd265f9156d9657c96ab57..26b062f0950d4072cace4bf00229cb983377765a 100644 (file)
--- 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 cdb499b8da00b543e27c3182c2ce371ddad68d69..9bd0cbac785ed93151de5c887233a5ca1635db45 100644 (file)
--- 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 46e833854b5babdbd33c87f64ec71c9b52857819..45ff501de6c0b636adee9a65ac02db3fba9baa2e 100644 (file)
--- 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 016ef75456ac3c0b1dcd76fad221335904aae008..67e6d40697077c2cb545a1a5e68891e2ff94a8eb 100644 (file)
--- 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 a0115cc6ec4788e32ae01c8d034a4e0d1902e1f2..5c8849f8cee742a34ae4640735d5adae421079ed 100644 (file)
--- 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 daf0b2af0b40e63ce944081b597258a6050aa3f3..69c34b5f7b648dfee94abf30629f92e81405d93a 100644 (file)
--- 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 ade371d39f755486d0f2c65cbfc6466d6fc489f4..61d2bb83f7f6bb8977b1098735e0b675e105b789 100644 (file)
--- 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 3ced5afad518ebbc7217468b21c1a601cce323ad..74492442a7438a6dcc278c3d20b03620e625125a 100644 (file)
--- 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 ac21df25cb72ba2406d32ddfb21709a1f23f60f0..26909c8fdb6f0b704da1cc2ca16606fa153063c0 100644 (file)
--- 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 ded0d8431bd2230efd80a1f650e3addfb6fe87f8..941b9e20a673e50d7b2a65eae649dfe02d637c62 100644 (file)
--- 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 c863d4176cfebed987cb350625110c3d1399933f..a1924fea0e6028d460757b93301dd27e7e59d373 100644 (file)
--- 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 574a76d51e7df0a3ed26ebd6a6215592ada61dd5..6c294c72e5b3bc265ec03fecaafe3eee06a9b6f0 100644 (file)
--- 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 900a50eb41c6ab0a987eaa33ecdae9539760f799..520cadeea6162dc7c14d0fef86312bf4fc1cf710 100644 (file)
--- 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 91353eea894acac893ea4e194b9208e0ebb474cb..2fbcabb623a228ff53276ff13c62452a63bd060c 100644 (file)
--- 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 b31ed869d63eeb00001adaef9c889647ec15c80d..89739ad1b56b75bf1abbc90781e44e759a31ff49 100644 (file)
--- 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 539f06f61fad0244250d301583a6836458fa8ac6..c39409608b36f818a89334fb319eecd01891819b 100644 (file)
--- 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 109717f7383d3fc044a283ec4b2278ee86baf430..2f819e914fbe7f3b0046081d266e821c2c0a589a 100644 (file)
--- 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 210178dc1d7ab65ebabafec4b14b0cff62be3676..9d3a9c304363f228d8ad7f64630530b1e1d32cdb 100644 (file)
--- 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 debe9ec6e14656edb8f0f9cbe04c0b5149b36736..073e762e13058842b4dc74ac0bc9cba40a11defe 100644 (file)
--- 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 7fe8dc507795f4627072549d2b061219ac83a906..12cef126353eb1149706610946390df670a56f50 100644 (file)
--- 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 ef5b4c0c3b598241441dc265ab232a01c1a53583..9c02f9c545905a4e0e9a8f47edaf4ff24a1d9548 100644 (file)
--- 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"