15 files changed, 31 insertions, 19 deletions
diff --git a/src/or/buffers.c b/src/or/buffers.c
index f0943c2fa0..7fdbcc81b7 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 defd0a25db..e919db1d90 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 62b27d6616..ed4a2d9bc8 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 d963a5c0de..edca17a416 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 6ea4608c01..f54e01ecf3 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 2da8b99748..1e403a5e8c 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 32ed70ab0d..b759f83e24 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 c8599bf759..c203b9bf43 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 d2bb017631..807a71c7fd 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 c967a69389..6dd23dd444 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 dbd4eef2eb..426856d298 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 44aa8123b4..a9170d8de8 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 535c88d8db..6a7093d96d 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 7d31b4e053..28116eec8e 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 26c260c92c..a33c6550bc 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[]);