[tor-commits] [tor/master] Make sure that every module in src/or has a brief description.

nickm at torproject.org nickm at torproject.org
Sat Feb 27 17:24:30 UTC 2016 

commit fe6ca826dfc4d107faead4d3293740f29ad88ac1
Author: Nick Mathewson <nickm at torproject.org>
Date:   Sat Feb 27 18:08:24 2016 +0100

    Make sure that every module in src/or has a brief description.
---
 src/or/addressmap.c   | 9 +++++++++
 src/or/buffers.c      | 3 ++-
 src/or/channel.c      | 6 +++++-
 src/or/channeltls.c   | 4 +++-
 src/or/circpathbias.c | 9 +++++++++
 src/or/circuitbuild.c | 4 +++-
 src/or/circuitlist.c  | 3 ++-
 src/or/circuitstats.c | 7 +++++++
 src/or/confparse.c    | 7 +++++++
 src/or/dnsserv.c      | 3 ++-
 src/or/fp_pair.c      | 8 ++++++++
 src/or/keypin.c       | 7 +++++++
 src/or/microdesc.c    | 7 +++++++
 src/or/nodelist.c     | 8 ++++++++
 src/or/ntmain.c       | 6 ++++++
 src/or/onion_ntor.c   | 6 ++++++
 src/or/periodic.c     | 6 ++++++
 src/or/routerkeys.c   | 8 ++++++++
 src/or/routerset.c    | 7 +++++++
 src/or/statefile.c    | 7 +++++++
 src/or/torcert.c      | 7 +++++++
 21 files changed, 126 insertions(+), 6 deletions(-)

diff --git a/src/or/addressmap.c b/src/or/addressmap.c
index 9c29fb2..26b062f 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 cdb499b..9bd0cba 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 46e8338..45ff501 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 016ef75..67e6d40 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 a0115cc..5c8849f 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 daf0b2a..69c34b5 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 ade371d..61d2bb8 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 3ced5af..7449244 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 ac21df2..26909c8 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 ded0d84..941b9e2 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 c863d41..a1924fe 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 574a76d..6c294c7 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 900a50e..520cade 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 91353ee..2fbcabb 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 b31ed86..89739ad 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 539f06f..c394096 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 109717f..2f819e9 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 210178d..9d3a9c3 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 debe9ec..073e762 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 7fe8dc5..12cef12 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 ef5b4c0..9c02f9c 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"

More information about the tor-commits mailing list