Add about 60 more DOCDOC comments to 0.2.3

Also, try to resolve some doxygen issues.  First, define a magic
"This is doxygen!" macro so that we take the correct branch in
various #if/#else/#endifs in order to get the right documentation.
Second, add in a few grouping @{ and @} entries in order to get some
variables and fields to get grouped together.

12 files changed, 36 insertions, 10 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 49a4afe733..ed6886ce36 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -156,7 +156,7 @@ tor_fopen_cloexec(const char *path, const char *mode)
   return result;
 }
 
-#ifdef HAVE_SYS_MMAN_H
+#if defined(HAVE_SYS_MMAN_H) || defined(RUNNING_DOXYGEN)
 /** Try to create a memory mapping for <b>filename</b> and return it.  On
  * failure, return NULL.  Sets errno properly, using ERANGE to mean
  * "empty file". */
@@ -501,10 +501,13 @@ tor_memmem(const void *_haystack, size_t hlen,
 #endif
 }
 
-/* Tables to implement ctypes-replacement TOR_IS*() functions.  Each table
+/**
+ * Tables to implement ctypes-replacement TOR_IS*() functions.  Each table
  * has 256 bits to look up whether a character is in some set or not.  This
  * fails on non-ASCII platforms, but it is hard to find a platform whose
  * character set is not a superset of ASCII nowadays. */
+
+/**@{*/
 const uint32_t TOR_ISALPHA_TABLE[8] =
   { 0, 0, 0x7fffffe, 0x7fffffe, 0, 0, 0, 0 };
 const uint32_t TOR_ISALNUM_TABLE[8] =
@@ -517,8 +520,10 @@ const uint32_t TOR_ISPRINT_TABLE[8] =
   { 0, 0xffffffff, 0xffffffff, 0x7fffffff, 0, 0, 0, 0x0 };
 const uint32_t TOR_ISUPPER_TABLE[8] = { 0, 0, 0x7fffffe, 0, 0, 0, 0, 0 };
 const uint32_t TOR_ISLOWER_TABLE[8] = { 0, 0, 0, 0x7fffffe, 0, 0, 0, 0 };
-/* Upper-casing and lowercasing tables to map characters to upper/lowercase
- * equivalents. */
+
+/** Upper-casing and lowercasing tables to map characters to upper/lowercase
+ * equivalents.  Used by tor_toupper() and tor_tolower(). */
+/**@{*/
 const char TOR_TOUPPER_TABLE[256] = {
   0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,
   16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,
@@ -555,6 +560,7 @@ const char TOR_TOLOWER_TABLE[256] = {
   224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,
   240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,
 };
+/**@}*/
 
 /** Helper for tor_strtok_r_impl: Advances cp past all characters in
  * <b>sep</b>, and returns its new value. */
@@ -1779,9 +1785,11 @@ make_path_absolute(char *fname)
 #ifndef HAVE__NSGETENVIRON
 #ifndef HAVE_EXTERN_ENVIRON_DECLARED
 /* Some platforms declare environ under some circumstances, others don't. */
+#ifndef RUNNING_DOXYGEN
 extern char **environ;
 #endif
 #endif
+#endif
 
 /** Return the current environment. This is a portable replacement for
  * 'environ'. */
@@ -2356,6 +2364,7 @@ tor_gettimeofday(struct timeval *timeval)
 #define TIME_FNS_NEED_LOCKS
 #endif
 
+/* DOCDOC correct_tm */
 static struct tm *
 correct_tm(int islocal, const time_t *timep, struct tm *resultbuf,
            struct tm *r)
diff --git a/src/common/compat_libevent.c b/src/common/compat_libevent.c
index 70e3baf9dd..e522a8f579 100644
--- a/src/common/compat_libevent.c
+++ b/src/common/compat_libevent.c
@@ -6,9 +6,8 @@
  * \brief Wrappers to handle porting between different versions of libevent.
  *
  * In an ideal world, we'd just use Libevent 2.0 from now on.  But as of June
- * 2009, Libevent 2.0 is still in alpha, and we will have old versions of
- * Libevent for the forseeable future.
- **/
+ * 2012, Libevent 1.4 is still all over, and some poor souls are stuck on
+ * Libevent 1.3e. */
 
 #include "orconfig.h"
 #include "compat.h"
@@ -57,7 +56,7 @@ typedef uint32_t le_version_t;
 
 static le_version_t tor_get_libevent_version(const char **v_out);
 
-#ifdef HAVE_EVENT_SET_LOG_CALLBACK
+#if defined(HAVE_EVENT_SET_LOG_CALLBACK) || defined(RUNNING_DOXYGEN)
 /** A string which, if it appears in a libevent log, should be ignored. */
 static const char *suppress_msg = NULL;
 /** Callback function passed to event_set_log() so we can intercept
diff --git a/src/common/compat_libevent.h b/src/common/compat_libevent.h
index 0247297177..95f633aaaa 100644
--- a/src/common/compat_libevent.h
+++ b/src/common/compat_libevent.h
@@ -59,6 +59,7 @@ struct timeval;
 int tor_event_base_loopexit(struct event_base *base, struct timeval *tv);
 #endif
 
+/* DOCDOC tor_libevent_cfg */
 typedef struct tor_libevent_cfg {
   int disable_iocp;
   int num_cpus;
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 8feac95acf..86f19dfb6a 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -69,7 +69,7 @@
 /** Longest recognized */
 #define MAX_DNS_LABEL_SIZE 63
 
-#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8)
+#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8) && !defined(RUNNING_DOXYGEN)
 /** @{ */
 /** On OpenSSL versions before 0.9.8, there is no working SHA256
  * implementation, so we use Tom St Denis's nice speedy one, slightly adapted
@@ -404,6 +404,8 @@ crypto_cipher_new_with_iv(const char *key, const char *iv)
   return env;
 }
 
+/** Return a new crypto_cipher_t with the provided <b>key</b> and an IV of all
+ * zero bytes.  */
 crypto_cipher_t *
 crypto_cipher_new(const char *key)
 {
diff --git a/src/common/log.c b/src/common/log.c
index f509ddcd6e..f0384a77e0 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -97,6 +97,7 @@ should_log_function_name(log_domain_mask_t domain, int severity)
 
 /** A mutex to guard changes to logfiles and logging. */
 static tor_mutex_t log_mutex;
+/* DOCDOC log_mutex_initialized */
 static int log_mutex_initialized = 0;
 
 /** Linked list of logfile_t. */
diff --git a/src/common/procmon.c b/src/common/procmon.c
index 85d2a2fe3f..4375b601c9 100644
--- a/src/common/procmon.c
+++ b/src/common/procmon.c
@@ -41,6 +41,7 @@ static void tor_process_monitor_poll_cb(evutil_socket_t unused1, short unused2,
 /* This struct may contain pointers into the original process
  * specifier string, but it should *never* contain anything which
  * needs to be freed. */
+/* DOCDOC parsed_process_specifier_t */
 struct parsed_process_specifier_t {
   pid_t pid;
 };
@@ -81,6 +82,7 @@ parse_process_specifier(const char *process_spec,
   return -1;
 }
 
+/* DOCDOC tor_process_monitor_t */
 struct tor_process_monitor_t {
   /** Log domain for warning messages. */
   log_domain_mask_t log_domain;
@@ -152,6 +154,7 @@ tor_validate_process_specifier(const char *process_spec,
 #define PERIODIC_TIMER_FLAGS (0)
 #endif
 
+/* DOCDOC poll_interval_tv */
 static struct timeval poll_interval_tv = {15, 0};
 /* Note: If you port this file to plain Libevent 2, you can make
  * poll_interval_tv const.  It has to be non-const here because in
diff --git a/src/common/procmon.h b/src/common/procmon.h
index 02eb2da61c..3bf60448c1 100644
--- a/src/common/procmon.h
+++ b/src/common/procmon.h
@@ -14,6 +14,7 @@
 
 typedef struct tor_process_monitor_t tor_process_monitor_t;
 
+/* DOCDOC tor_procmon_callback_t */
 typedef void (*tor_procmon_callback_t)(void *);
 
 int tor_validate_process_specifier(const char *process_spec,
diff --git a/src/common/torlog.h b/src/common/torlog.h
index 4c5729ef53..d6b21dfd89 100644
--- a/src/common/torlog.h
+++ b/src/common/torlog.h
@@ -153,7 +153,7 @@ void tor_log(int severity, log_domain_mask_t domain, const char *format, ...)
   CHECK_PRINTF(3,4);
 #define log tor_log /* hack it so we don't conflict with log() as much */
 
-#ifdef __GNUC__
+#if defined(__GNUC__) || defined(RUNNING_DOXYGEN)
 extern int _log_global_min_severity;
 
 void _log_fn(int severity, log_domain_mask_t domain,
diff --git a/src/common/tortls.c b/src/common/tortls.c
index a069ebf052..06f645011f 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -225,6 +225,7 @@ static int check_cert_lifetime_internal(int severity, const X509 *cert,
 /** Global TLS contexts. We keep them here because nobody else needs
  * to touch them. */
 static tor_tls_context_t *server_tls_context = NULL;
+/* DOCDOC client_tls_context */
 static tor_tls_context_t *client_tls_context = NULL;
 
 /** True iff tor_tls_init() has been called. */
@@ -268,6 +269,7 @@ tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz)
   tor_snprintf(buf, sz, "%s%s", ssl_state, tortls_state);
 }
 
+/* DOCDOC tor_tls_log_one_error */
 void
 tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
                   int severity, int domain, const char *doing)
@@ -1342,6 +1344,7 @@ tor_tls_client_is_using_v2_ciphers(const SSL *ssl, const char *address)
   return 1;
 }
 
+/* DOCDOC tor_tls_debug_state_callback */
 static void
 tor_tls_debug_state_callback(const SSL *ssl, int type, int val)
 {
@@ -1621,6 +1624,7 @@ tor_tls_block_renegotiation(tor_tls_t *tls)
   tls->ssl->s3->flags &= ~SSL3_FLAGS_ALLOW_UNSAFE_LEGACY_RENEGOTIATION;
 }
 
+/* DOCDOC tor_tls_assert_renegotiation_unblocked */
 void
 tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls)
 {
diff --git a/src/common/util.c b/src/common/util.c
index b3145aefe3..e0de262078 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -3303,6 +3303,7 @@ tor_process_get_stdout_pipe(process_handle_t *process_handle)
   return process_handle->stdout_pipe;
 }
 #else
+/* DOCDOC tor_process_get_stdout_pipe */
 FILE *
 tor_process_get_stdout_pipe(process_handle_t *process_handle)
 {
@@ -3310,6 +3311,7 @@ tor_process_get_stdout_pipe(process_handle_t *process_handle)
 }
 #endif
 
+/* DOCDOC process_handle_new */
 static process_handle_t *
 process_handle_new(void)
 {
@@ -4289,6 +4291,7 @@ get_string_from_pipe(FILE *stream, char *buf_out, size_t count)
   return IO_STREAM_TERM;
 }
 
+/* DOCDOC tor_check_port_forwarding */
 void
 tor_check_port_forwarding(const char *filename, int dir_port, int or_port,
                           time_t now)
diff --git a/src/common/util.h b/src/common/util.h
index ae40898de7..de22e186c7 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -72,6 +72,7 @@
 /* Memory management */
 void *_tor_malloc(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_malloc_zero(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
+/* DOCDOC _tor_malloc_roundup */
 void *_tor_malloc_roundup(size_t *size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_calloc(size_t nmemb, size_t size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_realloc(void *ptr, size_t size DMALLOC_PARAMS);
@@ -382,6 +383,7 @@ HANDLE load_windows_system_library(const TCHAR *library_name);
 
 int environment_variable_names_equal(const char *s1, const char *s2);
 
+/* DOCDOC process_environment_t */
 struct process_environment_t {
   /** A pointer to a sorted empty-string-terminated sequence of
    * NUL-terminated strings of the form "NAME=VALUE". */
diff --git a/src/common/util_codedigest.c b/src/common/util_codedigest.c
index 88fe508b92..ef7095418b 100644
--- a/src/common/util_codedigest.c
+++ b/src/common/util_codedigest.c
@@ -1,6 +1,7 @@
 
 #include "util.h"
 
+/** DOCDOC */
 const char *
 libor_get_digests(void)
 {