r11629@catbus: nickm | 2007-02-02 15:06:17 -0500

 Removing the last DOCDOC comment hurt so much that I had to use Doxygen to identify undocumented macros and comments, and add 150 more DOCDOCs to point out where they were.  Oops.  Hey, kids!  Fixing some of these could be your first Tor patch!


svn:r9477

32 files changed, 205 insertions, 44 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 9c9da66d6..4d37363a9 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -107,17 +107,20 @@ const char compat_c_id[] =
 #include "strlcat.c"
 #endif
 
-/* used by inet_addr, not defined on solaris anywhere!? */
 #ifndef INADDR_NONE
+/* This is used by inet_addr, but apparently Solaris doesn't define it
+ * anyplace. */
 #define INADDR_NONE ((unsigned long) -1)
 #endif
 
 #ifdef HAVE_SYS_MMAN_H
+/** DOCDOC */
 typedef struct tor_mmap_impl_t {
   tor_mmap_t base;
   size_t mapping_size; /**< Size of the actual mapping. (This is this file
                         * size, rounded up to the nearest page.) */
 } tor_mmap_impl_t;
+/** DOCDOC */
 tor_mmap_t *
 tor_mmap_file(const char *filename)
 {
@@ -165,6 +168,7 @@ tor_mmap_file(const char *filename)
 
   return &(res->base);
 }
+/** DOCDOC */
 void
 tor_munmap_file(tor_mmap_t *handle)
 {
@@ -174,6 +178,7 @@ tor_munmap_file(tor_mmap_t *handle)
   tor_free(h);
 }
 #elif defined(MS_WINDOWS)
+/** DOCDOC */
 typedef struct win_mmap_t {
   tor_mmap_t base;
   HANDLE file_handle;
@@ -966,6 +971,7 @@ typedef struct tor_pthread_data_t {
   void (*func)(void *);
   void *data;
 } tor_pthread_data_t;
+/** DOCDOC */
 static void *
 tor_pthread_helper_fn(void *_data)
 {
@@ -1092,6 +1098,8 @@ tor_gettimeofday(struct timeval *timeval)
 }
 
 #if defined(TOR_IS_MULTITHREADED) && !defined(MS_WINDOWS)
+/** Defined iff we need to add locks when defining fake versions of reentrant
+ * versions of time-related functions. */
 #define TIME_FNS_NEED_LOCKS
 #endif
 
@@ -1206,6 +1214,7 @@ tor_get_thread_id(void)
 struct tor_mutex_t {
   pthread_mutex_t mutex;
 };
+/** DOCDOC */
 tor_mutex_t *
 tor_mutex_new(void)
 {
@@ -1213,18 +1222,21 @@ tor_mutex_new(void)
   pthread_mutex_init(&mutex->mutex, NULL);
   return mutex;
 }
+/** DOCDOC */
 void
 tor_mutex_acquire(tor_mutex_t *m)
 {
   tor_assert(m);
   pthread_mutex_lock(&m->mutex);
 }
+/** DOCDOC */
 void
 tor_mutex_release(tor_mutex_t *m)
 {
   tor_assert(m);
   pthread_mutex_unlock(&m->mutex);
 }
+/** DOCDOC */
 void
 tor_mutex_free(tor_mutex_t *m)
 {
@@ -1232,6 +1244,7 @@ tor_mutex_free(tor_mutex_t *m)
   pthread_mutex_destroy(&m->mutex);
   tor_free(m);
 }
+/** DOCDOC */
 unsigned long
 tor_get_thread_id(void)
 {
diff --git a/src/common/container.c b/src/common/container.c
index 659e1346d..efbadc6d2 100644
--- a/src/common/container.c
+++ b/src/common/container.c
@@ -28,8 +28,7 @@ const char container_c_id[] =
 
 #include "ht.h"
 
-/* All newly allocated smartlists have this capacity.
- */
+/** All newly allocated smartlists have this capacity. */
 #define SMARTLIST_DEFAULT_CAPACITY 32
 
 /** Allocate and return an empty smartlist.
diff --git a/src/common/container.h b/src/common/container.h
index a6b7b56ad..8fbc863cb 100644
--- a/src/common/container.h
+++ b/src/common/container.h
@@ -11,7 +11,12 @@
 #include "compat.h"
 #include "util.h"
 
-/** A resizeable list of pointers, with associated helpful functionality. */
+/** A resizeable list of pointers, with associated helpful functionality.
+ *
+ * The members of this struct are exposed only so that macros and inlines can
+ * use them; all access to smartlist internals should go throuch the functions
+ * and macros defined here.
+ **/
 typedef struct smartlist_t {
   /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
    * before it needs to be resized.  Only the first <b>num_used</b> (\<=
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 00f3cf460..0af144d23 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -550,7 +550,7 @@ crypto_pk_read_public_key_from_string(crypto_pk_env_t *env, const char *src,
   return 0;
 }
 
-/* Write the private key from 'env' into the file named by 'fname',
+/** Write the private key from 'env' into the file named by 'fname',
  * PEM-encoded.  Return 0 on success, -1 on failure.
  */
 int
diff --git a/src/common/crypto.h b/src/common/crypto.h
index 375e2c550..f09936ef9 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -160,12 +160,14 @@ void *smartlist_choose(const struct smartlist_t *sl);
 
 int base64_encode(char *dest, size_t destlen, const char *src, size_t srclen);
 int base64_decode(char *dest, size_t destlen, const char *src, size_t srclen);
+/** Characters that can appear (case-insensitively) in a base-32 encoding. */
 #define BASE32_CHARS "abcdefghijklmnopqrstuvwxyz234567"
 void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);
 
 int digest_to_base64(char *d64, const char *digest);
 int digest_from_base64(char *digest, const char *d64);
 
+/** DOCDOC */
 #define S2K_SPECIFIER_LEN 9
 void secret_to_key(char *key_out, size_t key_out_len, const char *secret,
                    size_t secret_len, const char *s2k_specifier);
diff --git a/src/common/log.h b/src/common/log.h
index 8122a94aa..c6b6a6aa6 100644
--- a/src/common/log.h
+++ b/src/common/log.h
@@ -90,6 +90,7 @@
 /** Bandwidth accounting. */
 #define LD_ACCT     (1u<<17)
 
+/** DOCDOC */
 typedef void (*log_callback)(int severity, uint32_t domain, const char *msg);
 
 int parse_log_level(const char *level);
diff --git a/src/common/torgzip.c b/src/common/torgzip.c
index badd45be8..ad9164940 100644
--- a/src/common/torgzip.c
+++ b/src/common/torgzip.c
@@ -299,6 +299,7 @@ detect_compression_method(const char *in, size_t in_len)
   }
 }
 
+/** DOCDOC */
 struct tor_zlib_state_t {
   struct z_stream_s stream;
   int compress;
diff --git a/src/common/torgzip.h b/src/common/torgzip.h
index a20106cc3..f8e15d75c 100644
--- a/src/common/torgzip.h
+++ b/src/common/torgzip.h
@@ -12,6 +12,7 @@
 #define __TORGZIP_H
 #define TORGZIP_H_ID "$Id$"
 
+/** DOCDOC */
 typedef enum {
   NO_METHOD=0, GZIP_METHOD=1, ZLIB_METHOD=2, UNKNOWN_METHOD=3
 } compress_method_t;
@@ -31,6 +32,7 @@ int is_gzip_supported(void);
 
 compress_method_t detect_compression_method(const char *in, size_t in_len);
 
+/** DOCDOC */
 typedef enum {
   TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
 }  tor_zlib_output_t;
diff --git a/src/common/tortls.c b/src/common/tortls.c
index 8238073a3..aab3cc4ef 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -103,6 +103,7 @@ tls_log_errors(int severity, const char *doing)
   }
 }
 
+/** DOCDOC */
 static int
 tor_errno_to_tls_error(int e)
 {
@@ -205,6 +206,7 @@ tor_tls_init(void)
   }
 }
 
+/** DOCDOC */
 void
 tor_tls_free_all(void)
 {
@@ -720,6 +722,7 @@ tor_tls_get_peer_cert_nickname(int severity, tor_tls_t *tls,
   return r;
 }
 
+/** DOCDOC */
 static void
 log_cert_lifetime(X509 *cert, const char *problem)
 {
diff --git a/src/common/tortls.h b/src/common/tortls.h
index 50e798cc2..1fe245aab 100644
--- a/src/common/tortls.h
+++ b/src/common/tortls.h
@@ -31,7 +31,7 @@ typedef struct tor_tls_t tor_tls_t;
 #define TOR_TLS_WANTWRITE          -1
 #define TOR_TLS_DONE                0
 
-/* Use this macro in a switch statement to catch _any_ TLS error.  That way,
+/** Use this macro in a switch statement to catch _any_ TLS error.  That way,
  * if more errors are added, your switches will still work. */
 #define CASE_TOR_TLS_ERROR_ANY                  \
   case TOR_TLS_ERROR_MISC:                      \
diff --git a/src/common/util.c b/src/common/util.c
index d7027b848..6ecb901ea 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -125,7 +125,7 @@ _tor_malloc(size_t size DMALLOC_PARAMS)
   return result;
 }
 
-/* Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
+/** Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
  * zero bytes, and return a pointer to the result.  Log and terminate
  * the process on error.  (Same as calloc(size,1), but never returns NULL.)
  */
@@ -361,7 +361,7 @@ tor_strisnonupper(const char *s)
   return 1;
 }
 
-/* Compares the first strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the first strlen(s2) characters of s1 with s2.  Returns as for
  * strcmp.
  */
 int
@@ -371,7 +371,7 @@ strcmpstart(const char *s1, const char *s2)
   return strncmp(s1, s2, n);
 }
 
-/* Compares the first strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the first strlen(s2) characters of s1 with s2.  Returns as for
  * strcasecmp.
  */
 int
@@ -381,7 +381,7 @@ strcasecmpstart(const char *s1, const char *s2)
   return strncasecmp(s1, s2, n);
 }
 
-/* Compares the last strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the last strlen(s2) characters of s1 with s2.  Returns as for
  * strcmp.
  */
 int
@@ -394,7 +394,7 @@ strcmpend(const char *s1, const char *s2)
     return strncmp(s1+(n1-n2), s2, n2);
 }
 
-/* Compares the last strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the last strlen(s2) characters of s1 with s2.  Returns as for
  * strcasecmp.
  */
 int
@@ -624,7 +624,7 @@ hex_decode_digit(char c)
   }
 }
 
-/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src/b>, decode it
+/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src</b>, decode it
  * and store the result in the <b>destlen</b>-byte buffer at <b>dest</b>.
  * Return 0 on success, -1 on failure. */
 int
@@ -878,7 +878,9 @@ tv_addms(struct timeval *a, long ms)
   a->tv_usec %= 1000000;
 }
 
+/** DOCDOC */
 #define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
+/** DOCDOC */
 static int
 n_leapdays(int y1, int y2)
 {
@@ -1263,7 +1265,7 @@ write_str_to_file(const char *fname, const char *str, int bin)
 }
 
 /** Helper: given a set of flags as passed to open(2), open the file
- * <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</t> to
+ * <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</b> to
  * the file.  Do so as atomically as possible e.g. by opening temp files and
  * renaming. */
 static int
@@ -1320,7 +1322,7 @@ write_chunks_to_file_impl(const char *fname, const smartlist_t *chunks,
   return -1;
 }
 
-/* Given a smartlist of sized_chunk_t, write them atomically to a file
+/** Given a smartlist of sized_chunk_t, write them atomically to a file
  * <b>fname</b>, overwriting or creating the file as necessary. */
 int
 write_chunks_to_file(const char *fname, const smartlist_t *chunks, int bin)
@@ -1962,8 +1964,11 @@ get_interface_address(int severity, uint32_t *addr)
 
 #ifndef MS_WINDOWS
 /* Based on code contributed by christian grothoff */
+/** DOCDOC */
 static int start_daemon_called = 0;
+/** DOCDOC */
 static int finish_daemon_called = 0;
+/** DOCDOC */
 static int daemon_filedes[2];
 /** Start putting the process into daemon mode: fork and drop all resources
  * except standard fds.  The parent process never returns, but stays around
diff --git a/src/common/util.h b/src/common/util.h
index b659e5f04..868f4cde2 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -39,10 +39,13 @@
 #error "Sorry; we don't support building with NDEBUG."
 #else
 #ifdef __GNUC__
+/** DOCDOC */
 #define PREDICT_FALSE(x) PREDICT((x) == ((typeof(x)) 0), 0)
 #else
 #define PREDICT_FALSE(x) !(x)
 #endif
+
+/** DOCDOC */
 #define tor_assert(expr) do {                                           \
     if (PREDICT_FALSE(expr)) {                                          \
       log(LOG_ERR, LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
@@ -106,6 +109,8 @@ extern int dmalloc_free(const char *file, const int line, void *pnt,
 #endif
 
 /* String manipulation */
+
+/** DOCDOC */
 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
 void tor_strlower(char *s) ATTR_NONNULL((1));
 void tor_strupper(char *s) ATTR_NONNULL((1));
@@ -118,6 +123,7 @@ int strcmpend(const char *s1, const char *s2) ATTR_PURE ATTR_NONNULL((1,2));
 int strcasecmpend(const char *s1, const char *s2)
   ATTR_PURE ATTR_NONNULL((1,2));
 int tor_strstrip(char *s, const char *strip) ATTR_NONNULL((1,2));
+/** DOCDOC */
 typedef enum {
   ALWAYS_TERMINATE, NEVER_TERMINATE, TERMINATE_IF_EVEN
 } part_finish_rule_t;
@@ -163,9 +169,11 @@ int parse_iso_time(const char *buf, time_t *t);
 int write_all(int fd, const char *buf, size_t count, int isSocket);
 int read_all(int fd, char *buf, size_t count, int isSocket);
 
+/** DOCDOC */
 typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR} file_status_t;
 file_status_t file_status(const char *filename);
 
+/** DOCDOC */
 typedef enum { CPD_NONE, CPD_CREATE, CPD_CHECK } cpd_check_t;
 int check_private_dir(const char *dirname, cpd_check_t check);
 int write_str_to_file(const char *fname, const char *str, int bin);
diff --git a/src/or/buffers.c b/src/or/buffers.c
index 050141a03..31b03b7db 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -22,7 +22,7 @@ const char buffers_c_id[] =
 
 #ifdef SENTINELS
 /* If SENTINELS is defined, check for attempts to write beyond the
- * end/before the start of the buffer.
+ * end/before the start of the buffer. DOCDOC macros
  */
 #define START_MAGIC 0x70370370u
 #define END_MAGIC 0xA0B0C0D0u
@@ -49,6 +49,7 @@ const char buffers_c_id[] =
 #define INLINE
 #endif
 
+/* DOCDOC */
 #define BUFFER_MAGIC 0xB0FFF312u
 /** A resizeable buffer, optimized for reading and writing. */
 struct buf_t {
diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index 5198aac1b..5a158f32e 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -288,7 +288,7 @@ origin_circuit_init(uint8_t purpose, int onehop_tunnel,
   return circ;
 }
 
-/** Build a new circuit for <b>purpose</b>. If <b>info/b>
+/** Build a new circuit for <b>purpose</b>. If <b>info</b>
  * is defined, then use that as your exit router, else choose a suitable
  * exit node.
  *
@@ -1117,6 +1117,7 @@ router_handles_some_port(routerinfo_t *router, smartlist_t *needed_ports)
   return 0;
 }
 
+/* DOCDOC */
 static int
 ap_stream_wants_exit_attention(connection_t *conn)
 {
@@ -1982,6 +1983,7 @@ control_event_guard_deferred(void)
 #endif
 }
 
+/* DOCDOC */
 #define NUM_ENTRY_PICK_TRIES 100
 
 /** Add a new (preferably stable and fast) router to our
diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c
index 2f01f75fd..2296ca765 100644
--- a/src/or/circuitlist.c
+++ b/src/or/circuitlist.c
@@ -48,12 +48,14 @@ _orconn_circid_entries_eq(orconn_circid_circuit_map_t *a,
   return a->or_conn == b->or_conn && a->circ_id == b->circ_id;
 }
 
+/** DOCDOC */
 static INLINE unsigned int
 _orconn_circid_entry_hash(orconn_circid_circuit_map_t *a)
 {
   return (((unsigned)a->circ_id)<<16) ^ (unsigned)(uintptr_t)(a->or_conn);
 }
 
+/** DOCDOC */
 static HT_HEAD(orconn_circid_map, orconn_circid_circuit_map_t)
      orconn_circid_circuit_map = HT_INITIALIZER();
 HT_PROTOTYPE(orconn_circid_map, orconn_circid_circuit_map_t, node,
@@ -279,6 +281,7 @@ origin_circuit_new(void)
   return circ;
 }
 
+/** DOCDOC */
 or_circuit_t *
 or_circuit_new(uint16_t p_circ_id, or_connection_t *p_conn)
 {
diff --git a/src/or/circuituse.c b/src/or/circuituse.c
index 36c7a0ac1..be68088a2 100644
--- a/src/or/circuituse.c
+++ b/src/or/circuituse.c
@@ -22,7 +22,7 @@ extern circuit_t *global_circuitlist; /* from circuitlist.c */
 static void circuit_expire_old_circuits(time_t now);
 static void circuit_increment_failure_count(void);
 
-/* Return 1 if <b>circ</b> could be returned by circuit_get_best().
+/** Return 1 if <b>circ</b> could be returned by circuit_get_best().
  * Else return 0.
  */
 static int
@@ -112,7 +112,7 @@ circuit_is_acceptable(circuit_t *circ, edge_connection_t *conn,
   return 1;
 }
 
-/* Return 1 if circuit <b>a</b> is better than circuit <b>b</b> for
+/** Return 1 if circuit <b>a</b> is better than circuit <b>b</b> for
  * <b>purpose</b>, and return 0 otherwise. Used by circuit_get_best.
  */
 static int
@@ -566,8 +566,10 @@ circuit_expire_old_circuits(time_t now)
   }
 }
 
+/** DOCDOC */
 #define NUM_PARALLEL_TESTING_CIRCS 4
 
+/** DOCDOC */
 static int have_performed_bandwidth_test = 0;
 
 /** Reset have_performed_bandwidth_test, so we'll start building
@@ -774,6 +776,7 @@ circuit_build_failed(origin_circuit_t *circ)
  * circuit_launch_new and circuit_*_failure_count.
  */
 static int n_circuit_failures = 0;
+/** DOCDOC */
 static int did_circs_fail_last_period = 0;
 
 /** Don't retry launching a new circuit if we try this many times with no
diff --git a/src/or/config.c b/src/or/config.c
index 7d7e788f0..eb6cdaf29 100644
--- a/src/or/config.c
+++ b/src/or/config.c
@@ -102,6 +102,7 @@ typedef struct config_var_t {
   const char *initvalue; /**< String (or null) describing initial value. */
 } config_var_t;
 
+/** DOCDOC */
 #define STRUCT_VAR_P(st, off) \
   ((void*) ( ((char*)st) + off ) )
 
@@ -511,6 +512,7 @@ static config_var_description_t state_description[] = {
   { NULL, NULL },
 };
 
+/** DOCDOC */
 typedef int (*validate_fn_t)(void*,void*,int,char**);
 
 /** Information on the keys, value types, key-to-struct-member mappings,
@@ -529,6 +531,7 @@ typedef struct {
   config_var_t *extra;
 } config_format_t;
 
+/** DOCDOC */
 #define CHECK(fmt, cfg) do {                                            \
     tor_assert(fmt && cfg);                                             \
     tor_assert((fmt)->magic ==                                          \
@@ -591,8 +594,10 @@ static void check_libevent_version(const char *m, int server);
 
 /*static*/ or_options_t *options_new(void);
 
+/** DOCDOC */
 #define OR_OPTIONS_MAGIC 9090909
 
+/** DOCDOC */
 static config_format_t options_format = {
   sizeof(or_options_t),
   OR_OPTIONS_MAGIC,
@@ -604,12 +609,15 @@ static config_format_t options_format = {
   NULL
 };
 
+/** DOCDOC */
 #define OR_STATE_MAGIC 0x57A73f57
 
+/** DOCDOC */
 static config_var_t state_extra_var = {
   "__extra", CONFIG_TYPE_LINELIST, STRUCT_OFFSET(or_state_t, ExtraLines), NULL
 };
 
+/** DOCDOC */
 static config_format_t state_format = {
   sizeof(or_state_t),
   OR_STATE_MAGIC,
@@ -1443,6 +1451,7 @@ option_get_assignment(or_options_t *options, const char *key)
   return get_assigned_option(&options_format, options, key);
 }
 
+/** DOCDOC */
 static config_line_t *
 config_lines_dup(const config_line_t *inp)
 {
@@ -1459,6 +1468,7 @@ config_lines_dup(const config_line_t *inp)
   return result;
 }
 
+/** DOCDOC */
 static config_line_t *
 get_assigned_option(config_format_t *fmt, or_options_t *options,
                     const char *key)
@@ -2135,7 +2145,7 @@ config_init(config_format_t *fmt, void *options)
   }
 }
 
-/* Allocate and return a new string holding the written-out values of the vars
+/** Allocate and return a new string holding the written-out values of the vars
  * in 'options'.  If 'minimal', do not write out any default-valued vars.
  * Else, if comment_defaults, write default values as comments.
  */
@@ -2230,7 +2240,7 @@ options_dump(or_options_t *options, int minimal)
   return config_dump(&options_format, options, minimal, 0);
 }
 
-/* Return 0 if every element of sl is a string holding a decimal
+/** Return 0 if every element of sl is a string holding a decimal
  * representation of a port number, or if sl is NULL.
  * Otherwise set *msg and return -1. */
 static int
@@ -3795,6 +3805,7 @@ static const struct {
   { NULL, LE_OTHER }
 };
 
+/** DOCDOC */
 static le_version_t
 decode_libevent_version(void)
 {
diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c
index 0afe3013c..a994be15b 100644
--- a/src/or/connection_edge.c
+++ b/src/or/connection_edge.c
@@ -24,7 +24,7 @@ const char connection_edge_c_id[] =
 #define TRANS_PF
 #endif
 
-/* List of exit_redirect_t */
+/** List of exit_redirect_t for every configured RedirectExit. */
 static smartlist_t *redirect_exit_list = NULL;
 
 static int connection_ap_handshake_process_socks(edge_connection_t *conn);
@@ -927,7 +927,7 @@ client_dns_set_reverse_addressmap(const char *address, const char *v,
  * application accidentally tried to connect to them directly (not
  * via Tor), it wouldn't get too far astray.
  *
- * Eventually, we should probably make this configurable.
+ * These options are configured by parse_virtual_addr_network().
  */
 static uint32_t virtual_addr_network = 0x7fc00000u;
 static uint32_t virtual_addr_netmask = 0xffc00000u;
@@ -1182,7 +1182,7 @@ addressmap_get_mappings(smartlist_t *sl, time_t min_expires,
    }
 }
 
-/* Connection <b>conn</b> just finished its socks handshake, or the
+/** Connection <b>conn</b> just finished its socks handshake, or the
  * controller asked us to take care of it. If <b>circ</b> is defined,
  * then that's where we'll want to attach it. Otherwise we have to
  * figure it out ourselves.
@@ -1394,6 +1394,7 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn,
                safe_str(conn->rend_query));
       rend_client_refetch_renddesc(conn->rend_query);
     } else { /* r > 0 */
+/** DOCDOC */
 #define NUM_SECONDS_BEFORE_REFETCH (60*15)
       if (time(NULL) - entry->received < NUM_SECONDS_BEFORE_REFETCH) {
         conn->_base.state = AP_CONN_STATE_CIRCUIT_WAIT;
diff --git a/src/or/connection_or.c b/src/or/connection_or.c
index 036a1b1dd..420d6b9fa 100644
--- a/src/or/connection_or.c
+++ b/src/or/connection_or.c
@@ -810,7 +810,9 @@ connection_or_count_pending_circs(or_connection_t *or_conn)
   return cnt;
 }
 
+/** DOCDOC */
 #define BUF_FULLNESS_THRESHOLD (128*1024)
+/** DOCDOC */
 #define BUF_EMPTINESS_THRESHOLD (96*1024)
 
 /** Return true iff there is so much data waiting to be flushed on <b>conn</b>
diff --git a/src/or/control.c b/src/or/control.c
index 0b34b0d8a..b02bbd34e 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -11,8 +11,10 @@ const char control_c_id[] =
 
 #include "or.h"
 
+/** DOCDOC */
 #define STATE_IS_OPEN(s) ((s) == CONTROL_CONN_STATE_OPEN_V0 ||          \
                           (s) == CONTROL_CONN_STATE_OPEN_V1)
+/** DOCDOC */
 #define STATE_IS_V0(s) ((s) == CONTROL_CONN_STATE_NEEDAUTH_V0 ||        \
                         (s) == CONTROL_CONN_STATE_OPEN_V0)
 
@@ -685,6 +687,7 @@ send_control1_event_string(uint16_t event, event_format_t which,
   }
 }
 
+/** DOCDOC */
 static void
 send_control1_event_impl(uint16_t event, event_format_t which, int extended,
                          const char *format, va_list ap)
@@ -1437,6 +1440,7 @@ handle_control_mapaddress(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
+/** DOCDOC */
 static int
 getinfo_helper_misc(control_connection_t *conn, const char *question,
                     char **answer)
@@ -1474,6 +1478,7 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
   return 0;
 }
 
+/** DOCDOC */
 static int
 getinfo_helper_dir(control_connection_t *control_conn,
                    const char *question, char **answer)
@@ -1581,6 +1586,7 @@ getinfo_helper_dir(control_connection_t *control_conn,
   return 0;
 }
 
+/** DOCDOC */
 static int
 getinfo_helper_events(control_connection_t *control_conn,
                       const char *question, char **answer)
@@ -1726,9 +1732,11 @@ getinfo_helper_events(control_connection_t *control_conn,
   return 0;
 }
 
+/** DOCDOC */
 typedef int (*getinfo_helper_t)(control_connection_t *,
                                 const char *q, char **a);
 
+/** DOCDOC */
 typedef struct getinfo_item_t {
   const char *varname;
   getinfo_helper_t fn;
@@ -1740,6 +1748,7 @@ typedef struct getinfo_item_t {
 #define PREFIX(name, fn, desc) { name, getinfo_helper_##fn, desc, 1 }
 #define DOC(name, desc) { name, NULL, desc, 0 }
 
+/** DOCDOC */
 static const getinfo_item_t getinfo_items[] = {
   ITEM("version", misc, "The current version of Tor."),
   ITEM("config-file", misc, "Current location of the \"torrc\" file."),
@@ -2537,6 +2546,7 @@ handle_control_closecircuit(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
+/** DOCDOC */
 static int
 handle_control_usefeature(control_connection_t *conn,
                           uint32_t len,
@@ -2966,6 +2976,7 @@ connection_control_process_inbuf(control_connection_t *conn)
     return connection_control_process_inbuf_v1(conn);
 }
 
+/** DOCDOC */
 static const char *
 circuit_end_reason_to_string(int reason)
 {
@@ -3231,6 +3242,7 @@ control_event_stream_status(edge_connection_t *conn, stream_status_event_t tp,
   return 0;
 }
 
+/** DOCDOC */
 static void
 orconn_target_get_name(int long_names,
                        char *name, size_t len, or_connection_t *conn)
@@ -3257,6 +3269,7 @@ orconn_target_get_name(int long_names,
   }
 }
 
+/** DOCDOC */
 int
 control_tls_error_to_reason(int e)
 {
@@ -3281,6 +3294,7 @@ control_tls_error_to_reason(int e)
   }
 }
 
+/** DOCDOC */
 static const char *
 or_conn_end_reason_to_string(int r)
 {
@@ -3309,6 +3323,7 @@ or_conn_end_reason_to_string(int r)
   }
 }
 
+/** DOCDOC */
 int
 control_event_or_conn_status(or_connection_t *conn,or_conn_status_event_t tp,
         int reason)
diff --git a/src/or/directory.c b/src/or/directory.c
index 3db8d938d..1b5468bd9 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -56,7 +56,8 @@ static void note_request(const char *key, size_t bytes);
 
 #define X_ADDRESS_HEADER "X-Your-Address-Is: "
 
-/* HTTP cache control: how long do we tell proxies they can cache things? */
+/** HTTP cache control: how long do we tell proxies they can cache each
+ * kind of document we serve? */
 #define FULL_DIR_CACHE_LIFETIME (60*60)
 #define RUNNINGROUTERS_CACHE_LIFETIME (20*60)
 #define NETWORKSTATUS_CACHE_LIFETIME (5*60)
@@ -1978,7 +1979,7 @@ connection_dir_finished_connecting(dir_connection_t *conn)
 }
 
 /** Called when one or more networkstatus fetches have failed (with uppercase
- * fingerprints listed in <b>failed</>).  Mark those fingerprints as having
+ * fingerprints listed in <b>failed</b>).  Mark those fingerprints as having
  * failed once, unless they failed with status code 503. */
 static void
 dir_networkstatus_download_failed(smartlist_t *failed, int status_code)
@@ -2054,7 +2055,7 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code)
   /* update_router_descriptor_downloads(time(NULL)); */
 }
 
-/* Given a directory <b>resource</b> request, containing zero
+/** Given a directory <b>resource</b> request, containing zero
  * or more strings separated by plus signs, followed optionally by ".z", store
  * the strings, in order, into <b>fp_out</b>.  If <b>compressed_out</b> is
  * non-NULL, set it to 1 if the resource ends in ".z", else set it to 0.  If
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index b196249e2..033cfefc1 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -52,6 +52,7 @@ static void clear_cached_dir(cached_dir_t *d);
 #define FP_REJECT  4  /**< We will not publish this router. */
 #define FP_BADEXIT 8 /**< We'll tell clients not to use this as an exit. */
 
+/** DOCDOC */
 typedef struct router_status_t {
   char nickname[MAX_NICKNAME_LEN+1];
   uint32_t status;
@@ -64,9 +65,10 @@ typedef struct authdir_config_t {
   digestmap_t *status_by_digest; /* Map from digest to FP_x mask */
 } authdir_config_t;
 
-/* Should be static; exposed for testing */
+/** Should be static; exposed for testing */
 authdir_config_t *fingerprint_list = NULL;
 
+/** DOCDOC */
 static authdir_config_t *
 authdir_config_new(void)
 {
@@ -574,6 +576,7 @@ dirserv_add_descriptor(const char *desc, const char **msg)
   }
 }
 
+/** DOCDOC */
 static INLINE int
 bool_neq(int a, int b)
 {
@@ -790,7 +793,7 @@ list_server_status(smartlist_t *routers, char **router_status_out,
   return 0;
 }
 
-/* Given a (possibly empty) list of config_line_t, each line of which contains
+/** Given a (possibly empty) list of config_line_t, each line of which contains
  * a list of comma-separated version numbers surrounded by optional space,
  * allocate and return a new string containing the version numbers, in order,
  * separated by commas.  Used to generate Recommended(Client|Server)?Versions
@@ -942,7 +945,7 @@ static cached_dir_t *the_directory = NULL;
 static cached_dir_t *cached_directory = NULL;
 static cached_dir_t cached_runningrouters = { NULL, NULL, 0, 0, 0, -1 };
 
-/* Used for other dirservers' v2 network statuses.  Map from hexdigest to
+/** Used for other dirservers' v2 network statuses.  Map from hexdigest to
  * cached_dir_t. */
 static digestmap_t *cached_v2_networkstatus = NULL;
 
@@ -1319,6 +1322,7 @@ dirserv_get_runningrouters(const char **rr, int compress)
 /** For authoritative directories: the current (v2) network status */
 static cached_dir_t *the_v2_networkstatus = NULL;
 
+/** DOCDOC */
 static int
 should_generate_v2_networkstatus(void)
 {
@@ -1468,8 +1472,11 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
 static cached_dir_t *
 generate_v2_networkstatus(void)
 {
+/** DOCDOC */
 #define LONGEST_STATUS_FLAG_NAME_LEN 9
+/** DOCDOC */
 #define N_STATUS_FLAGS 9
+/** DOCDOC */
 #define RS_ENTRY_LEN                                                    \
   ( /* first line */                                                    \
    MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
@@ -1988,7 +1995,7 @@ connection_dirserv_remove_from_blocked_list(or_connection_t *or_conn,
   tor_assert(!dir_conn->is_blocked_on_or_conn);
 }
 
-/* If <b>dir_conn</b> is a dirserv connection that's bridged over an edge_conn
+/** If <b>dir_conn</b> is a dirserv connection that's bridged over an edge_conn
  * onto an or_conn, remove it from the blocked list (if it's blocked) and
  * unlink it and the edge_conn from one another. */
 void
@@ -2190,7 +2197,7 @@ connection_dirserv_add_dir_bytes_to_outbuf(dir_connection_t *conn)
   return 0;
 }
 
-/* Spooling helper: Called when we're spooling networkstatus objects on
+/** Spooling helper: Called when we're spooling networkstatus objects on
  * <b>conn</b>, and the outbuf has become too empty.  If the current
  * networkstatus object (in <b>conn</b>-\>cached_dir) has more data, pull data
  * from there.  Otherwise, pop the next fingerprint from fingerprint_stack,
diff --git a/src/or/dns.c b/src/or/dns.c
index b7f27c64b..b36f5ed11 100644
--- a/src/or/dns.c
+++ b/src/or/dns.c
@@ -68,6 +68,7 @@ typedef struct pending_connection_t {
   struct pending_connection_t *next;
 } pending_connection_t;
 
+/** DOCDOC */
 #define CACHED_RESOLVE_MAGIC 0x1234F00D
 
 /* Possible states for a cached resolve_t */
diff --git a/src/or/hibernate.c b/src/or/hibernate.c
index 29736e692..22f6e6f0f 100644
--- a/src/or/hibernate.c
+++ b/src/or/hibernate.c
@@ -25,18 +25,24 @@ hibernating, phase 2:
 
 #include "or.h"
 
+/** DOCDOC */
 #define HIBERNATE_STATE_LIVE 1
+/** DOCDOC */
 #define HIBERNATE_STATE_EXITING 2
+/** DOCDOC */
 #define HIBERNATE_STATE_LOWBANDWIDTH 3
+/** DOCDOC */
 #define HIBERNATE_STATE_DORMANT 4
 
 extern long stats_n_seconds_working; /* published uptime */
 
+/** DOCDOC */
 static int hibernate_state = HIBERNATE_STATE_LIVE;
 /** If are hibernating, when do we plan to wake up? Set to 0 if we
  * aren't hibernating. */
 static time_t hibernate_end_time = 0;
 
+/** DOCDOC */
 typedef enum {
   UNIT_MONTH=1, UNIT_WEEK=2, UNIT_DAY=3,
 } time_unit_t;
@@ -69,8 +75,9 @@ typedef enum {
  * step one.
  */
 
-/** How many bytes have we read/written in this accounting interval? */
+/** How many bytes have we read in this accounting interval? */
 static uint64_t n_bytes_read_in_interval = 0;
+/** How many bytes have we written in this accounting interval? */
 static uint64_t n_bytes_written_in_interval = 0;
 /** How many seconds have we been running this interval? */
 static uint32_t n_seconds_active_in_interval = 0;
diff --git a/src/or/main.c b/src/or/main.c
index 751777034..bd7de8ea2 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -58,6 +58,7 @@ static time_t time_to_check_for_correct_dns = 0;
 /** Array of all open connections.  The first n_conns elements are valid. */
 static connection_t *connection_array[MAXCONNECTIONS+1] =
         { NULL };
+/** DOCDOC */
 static smartlist_t *closeable_connection_lst = NULL;
 
 static int n_conns=0; /**< Number of connections currently active. */
@@ -814,6 +815,7 @@ run_scheduled_events(time_t now)
       if (any_trusted_dir_is_v1_authority())
         directory_get_from_dirserver(DIR_PURPOSE_FETCH_DIR, NULL, 1);
     }
+/** DOCDOC */
 #define V1_DIR_FETCH_PERIOD (6*60*60)
     time_to_fetch_directory = now + V1_DIR_FETCH_PERIOD;
   }
@@ -823,6 +825,7 @@ run_scheduled_events(time_t now)
     if (!authdir_mode(options) || !options->V1AuthoritativeDir) {
       directory_get_from_dirserver(DIR_PURPOSE_FETCH_RUNNING_LIST, NULL, 1);
     }
+/** DOCDOC */
 #define V1_RUNNINGROUTERS_FETCH_PERIOD (30*60)
     time_to_fetch_running_routers = now + V1_RUNNINGROUTERS_FETCH_PERIOD;
 
@@ -949,7 +952,9 @@ run_scheduled_events(time_t now)
   }
 }
 
+/** DOCDOC */
 static struct event *timeout_event = NULL;
+/** DOCDOC */
 static int n_libevent_errors = 0;
 
 /** Libevent callback: invoked once every second. */
diff --git a/src/or/onion.c b/src/or/onion.c
index c9556db25..4425d46ba 100644
--- a/src/or/onion.c
+++ b/src/or/onion.c
@@ -25,7 +25,7 @@ typedef struct onion_queue_t {
 /** 5 seconds on the onion queue til we just send back a destroy */
 #define ONIONQUEUE_WAIT_CUTOFF 5
 
-/** Global (within this file) variables used by the next few functions */
+/** DOCDOC */
 static onion_queue_t *ol_list=NULL;
 static onion_queue_t *ol_tail=NULL;
 /** Length of ol_list */
@@ -359,10 +359,10 @@ onion_skin_client_handshake(crypto_dh_env_t *handshake_state,
 
 /** Implement the server side of the CREATE_FAST abbreviated handshake.  The
  * client has provided DIGEST_LEN key bytes in <b>key_in</b> ("x").  We
- * generate a reply of DIGEST_LEN*2 bytes in <b>key_out/b>, consisting of a
+ * generate a reply of DIGEST_LEN*2 bytes in <b>key_out</b>, consisting of a
  * new random "y", followed by H(x|y) to check for correctness.  We set
  * <b>key_out_len</b> bytes of key material in <b>key_out</b>.
- * Return 0 on success, <0 on failure.
+ * Return 0 on success, &lt;0 on failure.
  **/
 int
 fast_server_handshake(const char *key_in, /* DIGEST_LEN bytes */
diff --git a/src/or/or.h b/src/or/or.h
index 303f3d2e0..d61d00ed3 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -155,23 +155,27 @@
 #define cell_t tor_cell_t
 #endif
 
+/** DOCDOC */
 #define MAX_NICKNAME_LEN 19
-/* Hex digest plus dollar sign. */
+/** DOCDOC: Hex digest plus dollar sign. */
 #define MAX_HEX_NICKNAME_LEN (HEX_DIGEST_LEN+1)
-/* $Hexdigest=nickname */
+/** DOCDOC: $Hexdigest=nickname */
 #define MAX_VERBOSE_NICKNAME_LEN (1+HEX_DIGEST_LEN+1+MAX_NICKNAME_LEN)
 
 /** Maximum size, in bytes, for resized buffers. */
 #define MAX_BUF_SIZE ((1<<24)-1)
+/** DOCDOC */
 #define MAX_DIR_SIZE MAX_BUF_SIZE
 
-/* For http parsing */
+/** For http parsing DOCDOC */
 #define MAX_HEADERS_SIZE 50000
+/** DOCDOC */
 #define MAX_BODY_SIZE 500000
 
 /** How long do we keep DNS cache entries before purging them (regardless of
  * their TTL)? */
 #define MAX_DNS_ENTRY_AGE (30*60)
+/** DOCDOC */
 #define DEFAULT_DNS_TTL (30*60)
 /** How long can a TTL be before we stop believing it? */
 #define MAX_DNS_TTL (3*60*60)
@@ -194,6 +198,7 @@
 /** How old do we let a networkstatus get before ignoring it? */
 #define NETWORKSTATUS_MAX_AGE (60*60*24)
 
+/** DOCDOC */
 typedef enum {
   CIRC_ID_TYPE_LOWER=0,
   CIRC_ID_TYPE_HIGHER=1
@@ -303,6 +308,7 @@ typedef enum {
 #define AP_CONN_STATE_NATD_WAIT 12
 #define _AP_CONN_STATE_MAX 12
 
+/** DOCDOC */
 #define AP_CONN_STATE_IS_UNATTACHED(s) \
   ((s) <= AP_CONN_STATE_CIRCUIT_WAIT || (s) == AP_CONN_STATE_NATD_WAIT)
 
@@ -321,12 +327,17 @@ typedef enum {
 #define DIR_CONN_STATE_SERVER_WRITING 6
 #define _DIR_CONN_STATE_MAX 6
 
+/** DOCDOC */
 #define DIR_CONN_IS_SERVER(conn) ((conn)->purpose == DIR_PURPOSE_SERVER)
 
 #define _CONTROL_CONN_STATE_MIN 1
+/** DOCDOC */
 #define CONTROL_CONN_STATE_OPEN_V0 1
+/** DOCDOC */
 #define CONTROL_CONN_STATE_OPEN_V1 2
+/** DOCDOC */
 #define CONTROL_CONN_STATE_NEEDAUTH_V0 3
+/** DOCDOC */
 #define CONTROL_CONN_STATE_NEEDAUTH_V1 4
 #define _CONTROL_CONN_STATE_MAX 4
 
@@ -507,17 +518,24 @@ typedef enum {
  * and are not intended to be put in relay end cells. They are here
  * to be more informative when sending back socks replies to the
  * application. */
+/** DOCDOC */
 #define END_STREAM_REASON_ALREADY_SOCKS_REPLIED 256
+/** DOCDOC */
 #define END_STREAM_REASON_CANT_ATTACH 257
+/** DOCDOC */
 #define END_STREAM_REASON_NET_UNREACHABLE 258
+/** DOCDOC */
 #define END_STREAM_REASON_SOCKSPROTOCOL 259
+/** DOCDOC */
 #define END_STREAM_REASON_CANT_FETCH_ORIG_DEST 260
+/** DOCDOC */
 #define END_STREAM_REASON_INVALID_NATD_DEST 261
 
 /** Bitwise-or this with the argument to control_event_stream_status
  * to indicate that the reason came from an END cell. */
 #define END_STREAM_REASON_FLAG_REMOTE     512
 
+/* DOCDOC */
 #define RESOLVED_TYPE_HOSTNAME 0
 #define RESOLVED_TYPE_IPV4 4
 #define RESOLVED_TYPE_IPV6 6
@@ -566,9 +584,13 @@ typedef enum {
 #define STREAMWINDOW_START 5000
 #define STREAMWINDOW_INCREMENT 500
 #else
+/** DOCDOC */
 #define CIRCWINDOW_START 1000
+/** DOCDOC */
 #define CIRCWINDOW_INCREMENT 100
+/** DOCDOC */
 #define STREAMWINDOW_START 500
+/** DOCDOC */
 #define STREAMWINDOW_INCREMENT 50
 #endif
 
@@ -584,15 +606,17 @@ typedef enum {
 /** How long to test reachability before complaining to the user. */
 #define TIMEOUT_UNTIL_UNREACHABILITY_COMPLAINT (20*60)
 
-/* legal characters in a nickname */
+/** legal characters in a nickname */
 #define LEGAL_NICKNAME_CHARACTERS \
   "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
 /** Name to use in client TLS certificates if no nickname is given.*/
 #define DEFAULT_CLIENT_NICKNAME "client"
 
+/** DOCDOC */
 #define SOCKS4_NETWORK_LEN 8
 
+/** DOCDOC */
 typedef enum {
   SOCKS5_SUCCEEDED                  = 0x00,
   SOCKS5_GENERAL_ERROR              = 0x01,
@@ -615,10 +639,14 @@ typedef enum {
  *         Relay payload           [498 bytes]
  */
 
+/** DOCDOC */
 #define CELL_PAYLOAD_SIZE 509
+/** DOCDOC */
 #define CELL_NETWORK_SIZE 512
 
+/** DOCDOC */
 #define RELAY_HEADER_SIZE (1+2+2+4+2)
+/** DOCDOC */
 #define RELAY_PAYLOAD_SIZE (CELL_PAYLOAD_SIZE-RELAY_HEADER_SIZE)
 
 /** Parsed onion routing cell.  All communication between nodes
@@ -642,10 +670,15 @@ typedef struct {
 typedef struct buf_t buf_t;
 typedef struct socks_request_t socks_request_t;
 
+/** DOCDOC */
 #define BASE_CONNECTION_MAGIC 0x7C3C304Eu
+/** DOCDOC */
 #define OR_CONNECTION_MAGIC 0x7D31FF03u
+/** DOCDOC */
 #define EDGE_CONNECTION_MAGIC 0xF0374013u
+/** DOCDOC */
 #define DIR_CONNECTION_MAGIC 0x9988ffeeu
+/** DOCDOC */
 #define CONTROL_CONNECTION_MAGIC 0x8abc765du
 
 /** Description of a connection to another host or process, and associated
diff --git a/src/or/policies.c b/src/or/policies.c
index c011fb171..1e682a769 100644
--- a/src/or/policies.c
+++ b/src/or/policies.c
@@ -12,10 +12,15 @@ const char policies_c_id[] = \
 
 #include "or.h"
 
+/** DOCDOC */
 static addr_policy_t *socks_policy = NULL;
+/** DOCDOC */
 static addr_policy_t *dir_policy = NULL;
+/** DOCDOC */
 static addr_policy_t *authdir_reject_policy = NULL;
+/** DOCDOC */
 static addr_policy_t *authdir_invalid_policy = NULL;
+/** DOCDOC */
 static addr_policy_t *authdir_badexit_policy = NULL;
 
 /** Parsed addr_policy_t describing which addresses we believe we can start
@@ -209,6 +214,8 @@ authdir_policy_badexit_address(uint32_t addr, uint16_t port)
 
 #define REJECT(arg) \
   do { *msg = tor_strdup(arg); goto err; } while (0)
+
+/** DOCDOC */
 int
 validate_addr_policies(or_options_t *options, char **msg)
 {
@@ -247,7 +254,7 @@ err:
 #undef REJECT
 }
 
-/* Parse <b>string</b> in the same way that the exit policy
+/** Parse <b>string</b> in the same way that the exit policy
  * is parsed, and put the processed version in *<b>policy</b>.
  * Ignore port specifiers.
  */
@@ -266,6 +273,7 @@ load_policy_from_option(config_line_t *config, addr_policy_t **policy,
   }
 }
 
+/** DOCDOC */
 void
 policies_parse_from_options(or_options_t *options)
 {
@@ -655,6 +663,7 @@ policy_write_item(char *buf, size_t buflen, addr_policy_t *policy)
   return (int)written;
 }
 
+/** DOCDOC */
 int
 getinfo_helper_policies(control_connection_t *conn,
                         const char *question, char **answer)
@@ -680,6 +689,7 @@ addr_policy_free(addr_policy_t *p)
   }
 }
 
+/** DOCDOC */
 void
 policies_free_all(void)
 {
diff --git a/src/or/rephist.c b/src/or/rephist.c
index e24b6ad20..95f04ba91 100644
--- a/src/or/rephist.c
+++ b/src/or/rephist.c
@@ -956,6 +956,7 @@ static uint32_t n_rend_client_ops = 0;
 static uint32_t n_rend_mid_ops = 0;
 static uint32_t n_rend_server_ops = 0;
 
+/** DOCDOC */
 void
 note_crypto_pk_op(pk_op_t operation)
 {
@@ -999,6 +1000,7 @@ note_crypto_pk_op(pk_op_t operation)
   }
 }
 
+/** DOCDOC */
 void
 dump_pk_ops(int severity)
 {
diff --git a/src/or/router.c b/src/or/router.c
index f2cf47f40..8b5905b4e 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -27,10 +27,14 @@ extern long stats_n_seconds_working;
 /** Private keys for this OR.  There is also an SSL key managed by tortls.c.
  */
 static tor_mutex_t *key_lock=NULL;
-static time_t onionkey_set_at=0; /* When was onionkey last changed? */
+static time_t onionkey_set_at=0; /**< When was onionkey last changed? */
+/** DOCDOC */
 static crypto_pk_env_t *onionkey=NULL;
+/** DOCDOC */
 static crypto_pk_env_t *lastonionkey=NULL;
+/** DOCDOC */
 static crypto_pk_env_t *identitykey=NULL;
+/** DOCDOC */
 static char identitykey_digest[DIGEST_LEN];
 
 /** Replace the current onion key with <b>k</b>.  Does not affect lastonionkey;
@@ -995,6 +999,7 @@ check_descriptor_bandwidth_changed(time_t now)
   }
 }
 
+/** DOCDOC */
 static void
 log_addr_has_changed(int severity, uint32_t prev, uint32_t cur)
 {
@@ -1045,6 +1050,7 @@ check_descriptor_ipaddress_changed(time_t now)
   }
 }
 
+/** DOCDOC */
 static uint32_t last_guessed_ip = 0;
 
 /** A directory authority told us our IP address is <b>suggestion</b>.
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 3060375e4..ff868823f 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -214,6 +214,7 @@ router_append_to_journal(signed_descriptor_t *desc)
   return 0;
 }
 
+/** DOCDOC */
 static int
 _compare_old_routers_by_age(const void **_a, const void **_b)
 {
@@ -221,6 +222,7 @@ _compare_old_routers_by_age(const void **_a, const void **_b)
   return r1->published_on - r2->published_on;
 }
 
+/** DOCDOC */
 static int
 _compare_routers_by_age(const void **_a, const void **_b)
 {
@@ -343,7 +345,7 @@ router_rebuild_store(int force)
   return r;
 }
 
-/* Load all cached router descriptors from the store. Return 0 on success and
+/** Load all cached router descriptors from the store. Return 0 on success and
  * -1 on failure.
  */
 int
@@ -931,6 +933,7 @@ router_get_advertised_bandwidth(routerinfo_t *router)
   return router->bandwidthrate;
 }
 
+/** DOCDOC */
 #define MAX_BELIEVABLE_BANDWIDTH 1500000 /* 1.5 MB/sec */
 
 /** Helper function:
@@ -1953,6 +1956,7 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
   return 0;
 }
 
+/** DOCDOC */
 static int
 _compare_old_routers_by_identity(const void **_a, const void **_b)
 {
@@ -1963,12 +1967,14 @@ _compare_old_routers_by_identity(const void **_a, const void **_b)
   return r1->published_on - r2->published_on;
 }
 
+/** DOCDOC */
 struct duration_idx_t {
   int duration;
   int idx;
   int old;
 };
 
+/** DOCDOC */
 static int
 _compare_duration_idx(const void *_d1, const void *_d2)
 {
@@ -2574,6 +2580,7 @@ router_get_combined_status_by_digest(const char *digest)
                            _compare_digest_to_routerstatus_entry);
 }
 
+/** DOCDOC */
 static local_routerstatus_t *
 router_get_combined_status_by_nickname(const char *nickname,
                                        int warn_if_unnamed)
@@ -2739,7 +2746,7 @@ update_networkstatus_cache_downloads(time_t now)
 /** How long (in seconds) does a client wait after getting a network status
  * before downloading the next in sequence? */
 #define NETWORKSTATUS_CLIENT_DL_INTERVAL (30*60)
-/* How many times do we allow a networkstatus download to fail before we
+/** How many times do we allow a networkstatus download to fail before we
  * assume that the authority isn't publishing? */
 #define NETWORKSTATUS_N_ALLOWABLE_FAILURES 3
 /** We are not a directory cache or authority.  Update our network-status list
@@ -3802,7 +3809,7 @@ router_list_client_downloadable(void)
 static void
 update_router_descriptor_client_downloads(time_t now)
 {
-  /* Max amount of hashes to download per request.
+  /** Max amount of hashes to download per request.
    * Since squid does not like URLs >= 4096 bytes we limit it to 96.
    *   4096 - strlen(http://255.255.255.255/tor/server/d/.z) == 4058
    *   4058/41 (40 for the hash and 1 for the + that separates them) => 98
@@ -4029,6 +4036,7 @@ update_router_descriptor_downloads(time_t now)
   }
 }
 
+/** DOCDOC */
 static int
 routerstatus_count_usable_entries(smartlist_t *entries)
 {
@@ -4040,7 +4048,9 @@ routerstatus_count_usable_entries(smartlist_t *entries)
   return count;
 }
 
+/** DOCDOC */
 static int have_min_dir_info = 0;
+/** DOCDOC */
 static int need_to_update_have_min_dir_info = 1;
 
 /** Return true iff we have enough networkstatus and router information to
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index 3e70e1aaf..ae564d366 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -709,6 +709,7 @@ router_parse_list_from_string(const char **s, smartlist_t *dest,
 static digestmap_t *verified_digests = NULL;
 #endif
 
+/** DOCDOC */
 void
 dump_distinct_digest_count(int severity)
 {
@@ -1121,6 +1122,7 @@ _compare_routerstatus_entries(const void **_a, const void **_b)
   return memcmp(a->identity_digest, b->identity_digest, DIGEST_LEN);
 }
 
+/** DOCDOC */
 static void
 _free_duplicate_routerstatus_entry(void *e)
 {