Make freelist_len in memarea.c static; document a few variables.

svn:r17741

7 files changed, 24 insertions, 18 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 6689eb8794..d5de6f58e1 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -1829,9 +1829,11 @@ tor_get_thread_id(void)
   return (unsigned long)GetCurrentThreadId();
 }
 #elif defined(USE_PTHREADS)
-/* DOCDOC attr_reentrant */
+/** A mutex attribute that we're going to use to tell pthreads that we want
+ * "reentrant" mutexes (i.e., once we can re-lock if we're already holding
+ * them.) */
 static pthread_mutexattr_t attr_reentrant;
-/* DOCDOC threads_initialized */
+/** True iff we've called tor_threads_init() */
 static int threads_initialized = 0;
 /** Initialize <b>mutex</b> so it can be locked.  Every mutex must be set
  * up eith tor_mutex_init() or tor_mutex_new(); not both. */
diff --git a/src/common/crypto.c b/src/common/crypto.c
index ae9edd16f8..6686017bc1 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -261,7 +261,7 @@ _crypto_new_pk_env_evp_pkey(EVP_PKEY *pkey)
   return _crypto_new_pk_env_rsa(rsa);
 }
 
-/* DOCDOC _crypto_pk_env_get_rsa */
+/** Helper, used by tor-checkkey.c.  Return the RSA from a crypto_pk_env_t. */
 RSA *
 _crypto_pk_env_get_rsa(crypto_pk_env_t *env)
 {
diff --git a/src/common/log.c b/src/common/log.c
index 224b93a467..f43181848f 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -104,7 +104,8 @@ static tor_mutex_t *log_mutex = NULL;
 /** Linked list of logfile_t. */
 static logfile_t *logfiles = NULL;
 #ifdef HAVE_SYSLOG_H
-/* DOCDOC syslog_count */
+/** The number of open syslog log handlers that we have.  When this reaches 0,
+ * we can close our connection to the syslog facility. */
 static int syslog_count = 0;
 #endif
 
@@ -118,8 +119,8 @@ static int syslog_count = 0;
 #define UNLOCK_LOGS() STMT_NIL
 #endif
 
-/* What's the lowest log level anybody cares about? */
-/* DOCDOC _log_global_min_severity */
+/** What's the lowest log level anybody cares about?  Checking this lets us
+ * bail out early from log_debug if we aren't debugging.  */
 int _log_global_min_severity = LOG_NOTICE;
 
 static void delete_log(logfile_t *victim);
diff --git a/src/common/memarea.c b/src/common/memarea.c
index 592d03b46c..93b9d4f921 100644
--- a/src/common/memarea.c
+++ b/src/common/memarea.c
@@ -61,10 +61,12 @@ struct memarea_t {
   memarea_chunk_t *first; /**< Top of the chunk stack: never NULL. */
 };
 
+/** How many chunks will we put into the freelist before freeing them? */
 #define MAX_FREELIST_LEN 4
-/* DOCDOC freelist_len */
-int freelist_len=0;
-/* DOCDOC freelist */
+/** The number of memarea chunks currently in our freelist. */
+static int freelist_len=0;
+/** A linked list of unused memory area chunks.  Used to prevent us from
+ * spinning in malloc/free loops. */
 static memarea_chunk_t *freelist = NULL;
 
 /** Helper: allocate a new memarea chunk of around <b>chunk_size</b> bytes. */
diff --git a/src/common/test.h b/src/common/test.h
index c7af49cbbe..c5166bae49 100644
--- a/src/common/test.h
+++ b/src/common/test.h
@@ -21,9 +21,6 @@
 #define PRETTY_FUNCTION ""
 #endif
 
-/* DOCDOC have_failed */
-extern int have_failed;
-
 #define test_fail_msg(msg)                                      \
   STMT_BEGIN                                                    \
     have_failed = 1;                                            \
diff --git a/src/common/util.c b/src/common/util.c
index 531f953c9c..84a40a82a6 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -1054,10 +1054,11 @@ tor_timegm(struct tm *tm)
 }
 
 /* strftime is locale-specific, so we need to replace those parts */
-/* DOCDOC WEEKDAY_NAMES */
+
+/** A c-locale array of 3-letter names of weekdays, starting with Sun. */
 static const char *WEEKDAY_NAMES[] =
   { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };
-/* DOCDOC MONTH_NAMES */
+/** A c-locale array of 3-letter names of months, starting with Jan. */
 static const char *MONTH_NAMES[] =
   { "Jan", "Feb", "Mar", "Apr", "May", "Jun",
     "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" };
@@ -1341,9 +1342,10 @@ update_approx_time(time_t now)
  * have up to <b>ftime_slop</b> seconds of inaccuracy; IOW, our window of
  * estimate for the current time is now + ftime_skew +/- ftime_slop.
  */
-/* DOCDOC ftime_skew */
+/** Our current estimate of our skew, such that we think the current time is
+ * closest to time(NULL)+ftime_skew. */
 static int ftime_skew = 0;
-/* DOCDOC ftime_slop */
+/** Tolerance during time comparisons, in seconds. */
 static int ftime_slop = 60;
 /** Set the largest amount of sloppiness we'll allow in fuzzy time
  * comparisons. */
diff --git a/src/or/test.c b/src/or/test.c
index b79f62cc29..521d557a2e 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -51,10 +51,12 @@ const char tor_svn_revision[] = "";
 #include <openssl/crypto.h>
 #endif
 
-/* DOCDOC have_failed */
+/** Set to true if any unit test has failed.  Mostly, this is set by the macros
+ * in test.h */
 int have_failed = 0;
 
-/* DOCDOC temp_dir */
+/** Temporary directory (set up by setup_directory) under which we store all
+ * our files during testing. */
 static char temp_dir[256];
 
 /** Select and create the temporary directory we'll use to run our unit tests.