flesh out the source file descriptions for doxygen

svn:r4404

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"

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"

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

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"

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

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>

src/common/log.h

@@ -6,7 +6,7 @@
 /**
  * \file log.h
  *
- * \brief Headers for logging functions.
+ * \brief Headers for log.c
  **/
 
 #ifndef __LOG_H

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>

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"

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.)

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.
  **/

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"

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"

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:

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.
  **/
 

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"
 

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.
  **/

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:

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) */

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

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"

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

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;

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.
  **/
 

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

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[]);