11 files changed, 32 insertions, 20 deletions
diff --git a/src/common/aes.c b/src/common/aes.c
index 1f7195cbc2..5079006399 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 4c46906a00..72bc173e49 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 f892cd6773..dea3f71622 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 d05d012694..1b418ca8ba 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 06245668cf..66c859b65e 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 e254eb0698..180c08a9f6 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 bfcb557e6d..bff4ab71b9 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 ec613b2c42..34845146d5 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 b6753e8aca..8d4438907d 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 900965b1e1..974d22afa7 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 a9441055df..191ef738f4 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.
  **/