26 files changed, 63 insertions, 39 deletions
diff --git a/src/common/aes.c b/src/common/aes.c
index 1f7195cbc..507900639 100644
--- a/src/common/aes.c
+++ b/src/common/aes.c
@@ -6,8 +6,11 @@ const char aes_c_id[] = "$Id$";
 
 /**
  * \file aes.c
- *
- * \brief Implementation of a simple AES counter mode.
+ * \brief Implements the AES cipher (with 128-bit keys and blocks),
+ * and a counter-mode stream cipher on top of AES.  This code is
+ * taken from the main Rijndael distribution.  (We include this
+ * because many people are running older versions of OpenSSL without
+ * AES support.)
  **/
 
 #include "orconfig.h"
diff --git a/src/common/compat.c b/src/common/compat.c
index 4c46906a0..72bc173e4 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -4,8 +4,16 @@
 /* $Id$ */
 const char compat_c_id[] = "$Id$";
 
-/* This is required on rh7 to make strptime not complain.
- */
+/**
+ * \file compat.c
+ * \brief Wrappers to make calls more portable.  This code defines
+ * functions such as tor_malloc, tor_snprintf, get/set various data types,
+ * renaming, setting socket options, switching user IDs.  It is basically
+ * where the non-portable items are conditionally included depending on
+ * the platform.
+ **/
+
+/* This is required on rh7 to make strptime not complain. */
 #define _GNU_SOURCE
 
 #include "orconfig.h"
diff --git a/src/common/container.c b/src/common/container.c
index f892cd677..dea3f7162 100644
--- a/src/common/container.c
+++ b/src/common/container.c
@@ -4,6 +4,13 @@
 /* $Id$ */
 const char container_c_id[] = "$Id$";
 
+/**
+ * \file container.c
+ * \brief Implements a smartlist (a resizable array) along
+ * with helper functions to use smartlists.  Also includes a
+ * splay-tree implementation of the string-to-void* map.
+ **/
+
 #include "compat.h"
 #include "util.h"
 #include "log.h"
@@ -17,10 +24,6 @@ const char container_c_id[] = "$Id$";
 #include <string.h>
 #include <assert.h>
 
-/* =====
- * smartlist_t: a simple resizeable array abstraction.
- * ===== */
-
 /* All newly allocated smartlists have this capacity.
  */
 #define SMARTLIST_DEFAULT_CAPACITY 32
diff --git a/src/common/crypto.c b/src/common/crypto.c
index d05d01269..1b418ca8b 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -6,8 +6,8 @@ const char crypto_c_id[] = "$Id$";
 
 /**
  * \file crypto.c
- *
- * \brief Low-level cryptographic functions.
+ * \brief Wrapper functions to present a consistent interface to
+ * public-key and symmetric cryptography operations from OpenSSL.
  **/
 
 #include "orconfig.h"
diff --git a/src/common/crypto.h b/src/common/crypto.h
index 06245668c..66c859b65 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -6,7 +6,7 @@
 /**
  * \file crypto.h
  *
- * \brief Headers for low-level cryptographic functions.
+ * \brief Headers for crypto.c
  **/
 
 #ifndef __CRYPTO_H
diff --git a/src/common/log.c b/src/common/log.c
index e254eb069..180c08a9f 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -6,9 +6,8 @@ const char log_c_id[] = "$Id$";
 
 /**
  * \file log.c
- *
  * \brief Functions to send messages to log files or the console.
- */
+ **/
 
 #include "orconfig.h"
 #include <stdarg.h>
diff --git a/src/common/log.h b/src/common/log.h
index bfcb557e6..bff4ab71b 100644
--- a/src/common/log.h
+++ b/src/common/log.h
@@ -6,7 +6,7 @@
 /**
  * \file log.h
  *
- * \brief Headers for logging functions.
+ * \brief Headers for log.c
  **/
 
 #ifndef __LOG_H
diff --git a/src/common/test.h b/src/common/test.h
index ec613b2c4..34845146d 100644
--- a/src/common/test.h
+++ b/src/common/test.h
@@ -9,7 +9,7 @@
 
 /**
  * \file test.h
- * \brief Headers for test.c
+ * \brief Macros used by unit tests.
  */
 
 #include <string.h>
diff --git a/src/common/torgzip.c b/src/common/torgzip.c
index b6753e8ac..8d4438907 100644
--- a/src/common/torgzip.c
+++ b/src/common/torgzip.c
@@ -6,8 +6,7 @@ const char torgzip_c_id[] = "$Id$";
 
 /**
  * \file torgzip.c
- *
- * \brief Simple in-memory gzip implementation.
+ * \brief A simple in-memory gzip implementation.
  **/
 
 #include "orconfig.h"
diff --git a/src/common/tortls.c b/src/common/tortls.c
index 900965b1e..974d22afa 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -6,9 +6,10 @@ const char tortls_c_id[] = "$Id$";
 
 /**
  * \file tortls.c
- *
- * \brief TLS wrappers for Tor.
+ * \brief Wrapper functions to present a consistent interface to
+ * TLS, SSL, and X.509 functions from OpenSSL.
  **/
+
 /* (Unlike other tor functions, these
  * are prefixed with tor_ in order to avoid conflicting with OpenSSL
  * functions and variables.)
diff --git a/src/common/util.c b/src/common/util.c
index a9441055d..191ef738f 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -6,7 +6,6 @@ const char util_c_id[] = "$Id$";
 
 /**
  * \file util.c
- *
  * \brief Common functions for strings, IO, network, data structures,
  * process control.
  **/
diff --git a/src/or/buffers.c b/src/or/buffers.c
index f0943c2fa..7fdbcc81b 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -7,7 +7,9 @@ const char buffers_c_id[] = "$Id$";
 
 /**
  * \file buffers.c
- * \brief Abstractions for buffered IO.
+ * \brief Implements a generic buffer interface.  Buffers are
+ * fairly opaque string holders that can read to or flush from:
+ * memory, file descriptors, or TLS connections.
  **/
 
 #include "or.h"
diff --git a/src/or/circuituse.c b/src/or/circuituse.c
index defd0a25d..e919db1d9 100644
--- a/src/or/circuituse.c
+++ b/src/or/circuituse.c
@@ -7,7 +7,7 @@ const char circuituse_c_id[] = "$Id$";
 
 /**
  * \file circuituse.c
- * \brief Launch the right sort of circuits, attach streams to them.
+ * \brief Launch the right sort of circuits and attach streams to them.
  **/
 
 #include "or.h"
diff --git a/src/or/command.c b/src/or/command.c
index 62b27d661..ed4a2d9bc 100644
--- a/src/or/command.c
+++ b/src/or/command.c
@@ -7,7 +7,7 @@ const char command_c_id[] = "$Id$";
 
 /**
  * \file command.c
- * \brief Functions for processing incoming cells
+ * \brief Functions for processing incoming cells.
  **/
 
 /* In-points to command.c:
diff --git a/src/or/config.c b/src/or/config.c
index d963a5c0d..edca17a41 100644
--- a/src/or/config.c
+++ b/src/or/config.c
@@ -4,9 +4,9 @@
 /* See LICENSE for licensing information */
 /* $Id$ */
 const char config_c_id[] = "$Id$";
+
 /**
  * \file config.c
- *
  * \brief Code to parse and interpret configuration files.
  **/
 
diff --git a/src/or/control.c b/src/or/control.c
index 6ea4608c0..f54e01ecf 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -5,9 +5,8 @@ const char control_c_id[] = "$Id$";
 
 /**
  * \file control.c
- *
  * \brief Implementation for Tor's control-socket interface.
- */
+ **/
 
 #include "or.h"
 
diff --git a/src/or/cpuworker.c b/src/or/cpuworker.c
index 2da8b9974..1e403a5e8 100644
--- a/src/or/cpuworker.c
+++ b/src/or/cpuworker.c
@@ -6,8 +6,9 @@ const char cpuworker_c_id[] = "$Id$";
 
 /**
  * \file cpuworker.c
- * \brief Run computation-intensive tasks (generally for crypto) in
- * a separate execution context. [OR only.]
+ * \brief Implements a farm of 'CPU worker' processes to perform
+ * CPU-intensive tasks in another thread or process, to not
+ * interrupt the main thread.
  *
  * Right now, we only use this for processing onionskins.
  **/
diff --git a/src/or/directory.c b/src/or/directory.c
index 32ed70ab0..b759f83e2 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -8,7 +8,9 @@ const char directory_c_id[] = "$Id$";
 
 /**
  * \file directory.c
- * \brief Implement directory HTTP protocol.
+ * \brief Code to send and fetch directories and router
+ * descriptors via HTTP.  Directories use dirserv.c to generate the
+ * results; clients use routers.c to parse them.
  **/
 
 /* In-points to directory.c:
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index c8599bf75..c203b9bf4 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -8,7 +8,8 @@ const char dirserv_c_id[] = "$Id$";
 
 /**
  * \file dirserv.c
- * \brief Directory server core implementation.
+ * \brief Directory server core implementation. Manages directory
+ * contents and generates directories.
  **/
 
 /** How far in the future do we allow a router to get? (seconds) */
diff --git a/src/or/dns.c b/src/or/dns.c
index d2bb01763..807a71c7f 100644
--- a/src/or/dns.c
+++ b/src/or/dns.c
@@ -6,7 +6,10 @@ const char dns_c_id[] = "$Id$";
 
 /**
  * \file dns.c
- * \brief Resolve hostnames in separate processes.
+ * \brief Implements a farm of 'DNS worker' threads or processes to
+ * perform DNS lookups for onion routers and cache the results.
+ * [This needs to be done in the background because of the lack of a
+ * good, ubiquitous asynchronous DNS implementation.]
  **/
 
 /* See http://elvin.dstc.com/ListArchive/elvin-dev/archive/2001/09/msg00027.html
diff --git a/src/or/main.c b/src/or/main.c
index c967a6938..6dd23dd44 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -7,7 +7,8 @@ const char main_c_id[] = "$Id$";
 
 /**
  * \file main.c
- * \brief Tor main loop and startup functions.
+ * \brief Toplevel module. Handles signals, multiplexes between
+ * connections, implements main loop, and drives scheduled events.
  **/
 
 #include "or.h"
diff --git a/src/or/or.h b/src/or/or.h
index dbd4eef2e..426856d29 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -6,9 +6,8 @@
 
 /**
  * \file or.h
- *
  * \brief Master header file for Tor-specific functionality.
- */
+ **/
 
 #ifndef __OR_H
 #define __OR_H
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 44aa8123b..a9170d8de 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -5,16 +5,15 @@
 /* $Id$ */
 const char routerlist_c_id[] = "$Id$";
 
-#include "or.h"
-
 /**
  * \file routerlist.c
- *
  * \brief Code to
  * maintain and access the global list of routerinfos for known
  * servers.
  **/
 
+#include "or.h"
+
 /****************************************************************************/
 
 static smartlist_t *trusted_dir_servers = NULL;
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index 535c88d8d..6a7093d96 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -7,7 +7,6 @@ const char routerparse_c_id[] = "$Id$";
 
 /**
  * \file routerparse.c
- *
  * \brief Code to parse and validate router descriptors and directories.
  **/
 
diff --git a/src/or/test.c b/src/or/test.c
index 7d31b4e05..28116eec8 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -4,6 +4,11 @@
 /* $Id$ */
 const char test_c_id[] = "$Id$";
 
+/**
+ * \file test.c
+ * \brief Unit tests for many pieces of the lower level Tor modules.
+ **/
+
 #include "orconfig.h"
 #include <stdio.h>
 #ifdef HAVE_FCNTL_H
diff --git a/src/or/tor_main.c b/src/or/tor_main.c
index 26c260c92..a33c6550b 100644
--- a/src/or/tor_main.c
+++ b/src/or/tor_main.c
@@ -6,7 +6,8 @@ const char tor_main_c_id[] = "$Id$";
 
 /**
  * \file tor_main.c
- * \brief Entry point for tor binary.
+ * \brief Stub module containing a main() function. Allows unit
+ * test binary to link against main.c.
  **/
 
 int tor_main(int argc, char *argv[]);