Add a bunch of doxygen for things in src/lib.

20 files changed, 165 insertions, 27 deletions

diff --git a/src/lib/arch/bytes.h b/src/lib/arch/bytes.h
index 4756ca2beb..245dc94bbe 100644
--- a/src/lib/arch/bytes.h
+++ b/src/lib/arch/bytes.h
@@ -16,12 +16,17 @@
 #include <string.h>
 #include "lib/cc/torint.h"
 
-/* The uint8 variants are defined to make the code more uniform. */
+/**
+ * Read an 8-bit from <b>cp</b>.
+ */
 static inline uint8_t
 get_uint8(const void *cp)
 {
   return *(const uint8_t*)(cp);
 }
+/**
+ * Store an 8-bit value from <b>v</b> to <b>cp</b>.
+ */
 static inline void
 set_uint8(void *cp, uint8_t v)
 {
@@ -93,7 +98,7 @@ set_uint64(void *cp, uint64_t v)
   memcpy(cp,&v,8);
 }
 
-#ifdef WORDS_BIGENDIAN
+#if defined(WORDS_BIGENDIAN)
 static inline uint16_t
 tor_htons(uint32_t a)
 {
@@ -130,6 +135,9 @@ tor_ntohll(uint64_t a)
   return a;
 }
 #else /* !defined(WORDS_BIGENDIAN) */
+/**
+ * Convert a 16-bit value from host order to network order (big-endian).
+ **/
 static inline uint16_t
 tor_htons(uint16_t a)
 {
@@ -139,12 +147,18 @@ tor_htons(uint16_t a)
     ((a & 0xff00) >> 8);
 }
 
+/**
+ * Convert a 16-bit value from network order (big-endian) to host order.
+ **/
 static inline uint16_t
 tor_ntohs(uint16_t a)
 {
   return tor_htons(a);
 }
 
+/**
+ * Convert a 32-bit value from host order to network order (big-endian).
+ **/
 static inline uint32_t
 tor_htonl(uint32_t a)
 {
@@ -156,6 +170,9 @@ tor_htonl(uint32_t a)
     ((a & 0xff000000) >>24);
 }
 
+/**
+ * Convert a 32-bit value from network order (big-endian) to host order.
+ **/
 static inline uint32_t
 tor_ntohl(uint32_t a)
 {
diff --git a/src/lib/ctime/di_ops.c b/src/lib/ctime/di_ops.c
index 89e0837ae9..a96a888b02 100644
--- a/src/lib/ctime/di_ops.c
+++ b/src/lib/ctime/di_ops.c
@@ -145,8 +145,11 @@ tor_memeq(const void *a, const void *b, size_t sz)
 
 /* Implement di_digest256_map_t as a linked list of entries. */
 struct di_digest256_map_t {
+  /** Pointer to the next entry in the list. */
   struct di_digest256_map_t *next;
+  /** Key for this entry. */
   uint8_t key[32];
+  /** Value for this entry. */
   void *val;
 };
 
diff --git a/src/lib/ctime/di_ops.h b/src/lib/ctime/di_ops.h
index 264b56a8c1..fea8f93e37 100644
--- a/src/lib/ctime/di_ops.h
+++ b/src/lib/ctime/di_ops.h
@@ -16,6 +16,8 @@
 
 int tor_memcmp(const void *a, const void *b, size_t sz);
 int tor_memeq(const void *a, const void *b, size_t sz);
+/** Perform a constant-time comparison of the <b>sz</b> bytes at <b>a</b> and
+ * <b>b</b>, yielding true if they are different, and false otherwise. */
 #define tor_memneq(a,b,sz) (!tor_memeq((a),(b),(sz)))
 
 /** Alias for the platform's memcmp() function.  This function is
@@ -24,7 +26,19 @@ int tor_memeq(const void *a, const void *b, size_t sz);
  * implementation.
  */
 #define fast_memcmp(a,b,c) (memcmp((a),(b),(c)))
+/** Alias for the platform's memcmp() function, for use in testing equality.
+ *
+ * This function is <em>not</em> data-independent: we define this alias so
+ * that we can mark cases where we are deliberately using a data-dependent
+ * memcmp() implementation.
+ */
 #define fast_memeq(a,b,c)  (0==memcmp((a),(b),(c)))
+/** Alias for the platform's memcmp() function, for use in testing inequality.
+ *
+ * This function is <em>not</em> data-independent: we define this alias so
+ * that we can mark cases where we are deliberately using a data-dependent
+ * memcmp() implementation.
+ */
 #define fast_memneq(a,b,c) (0!=memcmp((a),(b),(c)))
 
 int safe_mem_is_zero(const void *mem, size_t sz);
@@ -35,9 +49,17 @@ int safe_mem_is_zero(const void *mem, size_t sz);
  *
  * Not efficient for large maps! */
 typedef struct di_digest256_map_t di_digest256_map_t;
+/**
+ * Type for a function used to free members of a di_digest256_map_t.
+ **/
 typedef void (*dimap_free_fn)(void *);
 
 void dimap_free_(di_digest256_map_t *map, dimap_free_fn free_fn);
+/**
+ * @copydoc dimap_free_
+ *
+ * Additionally, set the pointer <b>map</b> to NULL.
+ **/
 #define dimap_free(map, free_fn)                \
   do {                                          \
     dimap_free_((map), (free_fn));              \
@@ -52,4 +74,3 @@ int select_array_member_cumulative_timei(const uint64_t *entries,
                                          uint64_t total, uint64_t rand_val);
 
 #endif /* !defined(TOR_DI_OPS_H) */
-
diff --git a/src/lib/defs/time.h b/src/lib/defs/time.h
index 459afbf42d..1609702706 100644
--- a/src/lib/defs/time.h
+++ b/src/lib/defs/time.h
@@ -17,7 +17,7 @@
 #define TOR_USEC_PER_SEC (1000000)
 /** How many nanoseconds per microsecond */
 #define TOR_NSEC_PER_USEC (1000)
-/* How many nanoseconds per millisecond */
+/** How many nanoseconds per millisecond */
 #define TOR_NSEC_PER_MSEC (1000*1000)
 
 #endif /* !defined(TOR_TIME_DEFS_H) */
diff --git a/src/lib/defs/x25519_sizes.h b/src/lib/defs/x25519_sizes.h
index 6431f0a2dd..080bb4282a 100644
--- a/src/lib/defs/x25519_sizes.h
+++ b/src/lib/defs/x25519_sizes.h
@@ -23,14 +23,22 @@
 /** Length of the result of a curve25519 handshake. */
 #define CURVE25519_OUTPUT_LEN 32
 
+/** Length of an Ed25519 public key */
 #define ED25519_PUBKEY_LEN 32
+/** Length of an Ed25519 secret key */
 #define ED25519_SECKEY_LEN 64
+/** Length of the seed that is ordinarily expanded to an Ed25519 secret
+ * key. */
 #define ED25519_SECKEY_SEED_LEN 32
+/** Length of an Ed25519 signature. */
 #define ED25519_SIG_LEN 64
 
+/** Length of a Curve25519 key when encoded in base 64, with padding. */
 #define CURVE25519_BASE64_PADDED_LEN 44
 
+/** Length of a Ed25519 key when encoded in base 64, without padding. */
 #define ED25519_BASE64_LEN 43
+/** Length of a Ed25519 signature when encoded in base 64, without padding. */
 #define ED25519_SIG_BASE64_LEN 86
 
 #endif /* !defined(TOR_X25519_SIZES_H) */
diff --git a/src/lib/fdio/fdio.c b/src/lib/fdio/fdio.c
index 078af6a9ba..bfda26a430 100644
--- a/src/lib/fdio/fdio.c
+++ b/src/lib/fdio/fdio.c
@@ -28,9 +28,10 @@
 #include <stdlib.h>
 #include <stdio.h>
 
-/** @{ */
-/** Some old versions of Unix didn't define constants for these values,
+/* Some old versions of Unix didn't define constants for these values,
  * and instead expect you to say 0, 1, or 2. */
+
+/** @cond */
 #ifndef SEEK_SET
 #define SEEK_SET 0
 #endif
@@ -40,7 +41,7 @@
 #ifndef SEEK_END
 #define SEEK_END 2
 #endif
-/** @} */
+/** @endcond */
 
 /** Return the position of <b>fd</b> with respect to the start of the file. */
 off_t
diff --git a/src/lib/geoip/country.h b/src/lib/geoip/country.h
index 2bff4f4477..e6d7d77e7e 100644
--- a/src/lib/geoip/country.h
+++ b/src/lib/geoip/country.h
@@ -16,6 +16,7 @@
 /** A signed integer representing a country code. */
 typedef int16_t country_t;
 
+/** Maximum value for country_t. */
 #define COUNTRY_MAX INT16_MAX
 
 #endif /* !defined(TOR_COUNTRY_H) */
diff --git a/src/lib/geoip/geoip.c b/src/lib/geoip/geoip.c
index 70b1c2dc8c..2e0be13c04 100644
--- a/src/lib/geoip/geoip.c
+++ b/src/lib/geoip/geoip.c
@@ -70,12 +70,18 @@ static smartlist_t *geoip_countries = NULL;
  * The index is encoded in the pointer, and 1 is added so that NULL can mean
  * not found. */
 static strmap_t *country_idxplus1_by_lc_code = NULL;
-/** Lists of all known geoip_ipv4_entry_t and geoip_ipv6_entry_t, sorted
- * by their respective ip_low. */
-static smartlist_t *geoip_ipv4_entries = NULL, *geoip_ipv6_entries = NULL;
-
-/** SHA1 digest of the GeoIP files to include in extra-info descriptors. */
+/** List of all known geoip_ipv4_entry_t sorted
+ * by their respective ip_low values. */
+static smartlist_t *geoip_ipv4_entries = NULL;
+/** List of all known geoip_ipv6_entry_t, sorted by their respective
+ * ip_low values. */
+static smartlist_t *geoip_ipv6_entries = NULL;
+
+/** SHA1 digest of the IPv4 GeoIP file to include in extra-info
+ * descriptors. */
 static char geoip_digest[DIGEST_LEN];
+/** SHA1 digest of the IPv6 GeoIP file to include in extra-info
+ * descriptors. */
 static char geoip6_digest[DIGEST_LEN];
 
 /** Return a list of geoip_country_t for all known countries. */
diff --git a/src/lib/geoip/geoip.h b/src/lib/geoip/geoip.h
index f872ebd25f..1407d0a1ea 100644
--- a/src/lib/geoip/geoip.h
+++ b/src/lib/geoip/geoip.h
@@ -31,6 +31,7 @@ int geoip_get_country_by_ipv6(const struct in6_addr *addr);
 
 /** A per-country GeoIP record. */
 typedef struct geoip_country_t {
+  /** A nul-terminated two-letter country-code. */
   char countrycode[3];
 } geoip_country_t;
 
diff --git a/src/lib/lock/compat_mutex.h b/src/lib/lock/compat_mutex.h
index e0c3d7cb78..6fd4c1eb08 100644
--- a/src/lib/lock/compat_mutex.h
+++ b/src/lib/lock/compat_mutex.h
@@ -58,6 +58,11 @@ void tor_mutex_init_nonrecursive(tor_mutex_t *m);
 void tor_mutex_acquire(tor_mutex_t *m);
 void tor_mutex_release(tor_mutex_t *m);
 void tor_mutex_free_(tor_mutex_t *m);
+/**
+ * @copydoc tor_mutex_free_
+ *
+ * Additionally, set the pointer <b>m</b> to NULL.
+ **/
 #define tor_mutex_free(m) FREE_AND_NULL(tor_mutex_t, tor_mutex_free_, (m))
 void tor_mutex_uninit(tor_mutex_t *m);
 
diff --git a/src/lib/lock/compat_mutex_pthreads.c b/src/lib/lock/compat_mutex_pthreads.c
index f82ad9f0e8..a7f5986ecb 100644
--- a/src/lib/lock/compat_mutex_pthreads.c
+++ b/src/lib/lock/compat_mutex_pthreads.c
@@ -17,8 +17,14 @@
  * "recursive" mutexes (i.e., once we can re-lock if we're already holding
  * them.) */
 static pthread_mutexattr_t attr_recursive;
+/**
+ * True iff <b>attr_recursive</b> has been initialized.
+ **/
 static int attr_initialized = 0;
 
+/**
+ * Initialize the locking module, if it is not already initialized.
+ **/
 void
 tor_locking_init(void)
 {
diff --git a/src/lib/memarea/memarea.h b/src/lib/memarea/memarea.h
index 9c23cf62e9..dd0ed57fb0 100644
--- a/src/lib/memarea/memarea.h
+++ b/src/lib/memarea/memarea.h
@@ -16,6 +16,9 @@ typedef struct memarea_t memarea_t;
 
 memarea_t *memarea_new(void);
 void memarea_drop_all_(memarea_t *area);
+/** @copydoc memarea_drop_all_
+ *
+ * Additionally, set <b>area</b> to NULL. */
 #define memarea_drop_all(area) \
   do {                                          \
     memarea_drop_all_(area);                    \
diff --git a/src/lib/pubsub/pubsub_build.h b/src/lib/pubsub/pubsub_build.h
index 5a0c5f5bd3..13ec09c983 100644
--- a/src/lib/pubsub/pubsub_build.h
+++ b/src/lib/pubsub/pubsub_build.h
@@ -85,6 +85,11 @@ struct dispatch_t *pubsub_builder_finalize(pubsub_builder_t *,
  **/
 void pubsub_items_clear_bindings(pubsub_items_t *items);
 
+/**
+ * @copydoc pubsub_items_free_
+ *
+ * Additionally, set the pointer <b>cfg</b> to NULL.
+ **/
 #define pubsub_items_free(cfg) \
   FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))
 void pubsub_items_free_(pubsub_items_t *cfg);
diff --git a/src/lib/pubsub/pubsub_check.c b/src/lib/pubsub/pubsub_check.c
index bf1196df2c..38723e56ed 100644
--- a/src/lib/pubsub/pubsub_check.c
+++ b/src/lib/pubsub/pubsub_check.c
@@ -9,7 +9,9 @@
  * @brief Enforce various requirements on a pubsub_builder.
  **/
 
+/** @{ */
 #define PUBSUB_PRIVATE
+/** @} */
 
 #include "lib/dispatch/dispatch_naming.h"
 #include "lib/dispatch/msgtypes.h"
diff --git a/src/lib/pubsub/pubsub_macros.h b/src/lib/pubsub/pubsub_macros.h
index 357e59fd54..5c02fc354d 100644
--- a/src/lib/pubsub/pubsub_macros.h
+++ b/src/lib/pubsub/pubsub_macros.h
@@ -163,7 +163,7 @@
  *      hookfn with the appropriate arguments.
  */
 
-/* Macro to declare common elements shared by DECLARE_MESSAGE and
+/** Macro to declare common elements shared by DECLARE_MESSAGE and
  * DECLARE_MESSAGE_INT.  Don't call this directly.
  *
  * Note that the "msg_arg_name" string constant is defined in each
@@ -288,7 +288,7 @@
   ( 0 ? (publish_fn__ ##messagename((msg_arg_type__##messagename)0), 1) \
     : 1)
 
-/*
+/**
  * This macro is for internal use.  It backs DISPATCH_ADD_PUB*()
  */
 #define DISPATCH_ADD_PUB_(connector, channel, messagename, flags)       \
@@ -322,7 +322,7 @@
 #define DISPATCH_ADD_PUB_EXCL(connector, channel, messagename)  \
     DISPATCH_ADD_PUB_(connector, channel, messagename, DISP_FLAG_EXCL)
 
-/*
+/**
  * This macro is for internal use. It backs DISPATCH_ADD_SUB*()
  */
 #define DISPATCH_ADD_SUB_(connector, channel, messagename, flags)       \
@@ -334,7 +334,7 @@
                     (flags),                                            \
                     __FILE__,                                           \
                     __LINE__)
-/*
+/**
  * Use a given connector and channel name to declare that this subsystem will
  * receive a given message type.
  *
diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h
index 35a30680ee..91abdb7d74 100644
--- a/src/lib/subsys/subsys.h
+++ b/src/lib/subsys/subsys.h
@@ -90,11 +90,19 @@ typedef struct subsys_fns_t {
 
 } subsys_fns_t;
 
+/**
+ * Lowest allowed subsystem level.
+ **/
 #define MIN_SUBSYS_LEVEL -100
+/**
+ * Highest allowed subsystem level.
+ **/
 #define MAX_SUBSYS_LEVEL 100
 
-/* All tor "libraries" (in src/libs) should have a subsystem level equal to or
- * less than this value. */
+/**
+ * All tor "libraries" (in src/libs) should have a subsystem level equal to or
+ * less than this value.
+ */
 #define SUBSYS_LEVEL_LIBS -10
 
 #endif /* !defined(TOR_SUBSYS_T) */
diff --git a/src/lib/testsupport/testsupport.h b/src/lib/testsupport/testsupport.h
index 90b7c43b19..833515c32f 100644
--- a/src/lib/testsupport/testsupport.h
+++ b/src/lib/testsupport/testsupport.h
@@ -15,17 +15,42 @@
 #ifndef TOR_TESTSUPPORT_H
 #define TOR_TESTSUPPORT_H
 
-#ifdef TOR_UNIT_TESTS
 /** The "STATIC" macro marks a function or variable that is static when
  * building Tor for production, but non-static when building the unit
- * tests. */
+ * tests.
+ *
+ * For example, a function declared as:
+ *
+ *     STATIC int internal_function(void);
+ *
+ * should be only visible for the file on which it is declared, and in the
+ * unit tests.
+ */
+#ifdef TOR_UNIT_TESTS
 #define STATIC
-#define EXTERN(type, name) extern type name;
 #else /* !defined(TOR_UNIT_TESTS) */
 #define STATIC static
-#define EXTERN(type, name)
 #endif /* defined(TOR_UNIT_TESTS) */
 
+/** The "EXTERN" macro is used along with "STATIC" for variables declarations:
+ * it expands to an extern declaration when Tor building unit tests, and to
+ * nothing otherwise.
+ *
+ * For example, to declare a variable as visible only visible in one
+ * file and in the unit tests, you would put this in the header:
+ *
+ *     EXTERN(int, local_variable)
+ *
+ * and this in the source:
+ *
+ *     STATIC int local_variable;
+ */
+#ifdef TOR_UNIT_TESTS
+#define EXTERN(type, name) extern type name;
+#else
+#define EXTERN(type, name)
+#endif
+
 /** Quick and dirty macros to implement test mocking.
  *
  * To use them, suppose that you have a function you'd like to mock
@@ -70,32 +95,42 @@
  *
  * @{ */
 #ifdef TOR_UNIT_TESTS
+/** Declare a mocked function. For use in headers. */
 #define MOCK_DECL(rv, funcname, arglist)     \
   rv funcname ##__real arglist;              \
   extern rv(*funcname) arglist
+/** Define the implementation of a mocked function. */
 #define MOCK_IMPL(rv, funcname, arglist)     \
   rv(*funcname) arglist = funcname ##__real; \
   rv funcname ##__real arglist
+/** As MOCK_DECL(), but allow attributes. */
 #define MOCK_DECL_ATTR(rv, funcname, arglist, attr) \
   rv funcname ##__real arglist attr;                \
   extern rv(*funcname) arglist
-#define MOCK_IMPL(rv, funcname, arglist)     \
-  rv(*funcname) arglist = funcname ##__real; \
-  rv funcname ##__real arglist
+/**
+ * Replace <b>func</b> (a mockable function) with a replacement function.
+ *
+ * Only usable when Tor has been built for unit tests. */
 #define MOCK(func, replacement)                 \
   do {                                          \
     (func) = (replacement);                     \
   } while (0)
+/** Replace <b>func</b> (a mockable function) with its original value.
+ *
+ * Only usable when Tor has been built for unit tests. */
 #define UNMOCK(func)                            \
   do {                                          \
     func = func ##__real;                       \
   } while (0)
 #else /* !defined(TOR_UNIT_TESTS) */
+/** Declare a mocked function. For use in headers. */
 #define MOCK_DECL(rv, funcname, arglist) \
   rv funcname arglist
-#define MOCK_DECL_ATTR(rv, funcname, arglist, attr) \
+/** As MOCK_DECL(), but allow  */
+#define MOCK_DECL_ATTR(rv, funcname, arglist, attr)     \
   rv funcname arglist attr
-#define MOCK_IMPL(rv, funcname, arglist) \
+/** Define the implementation of a mocked function. */
+#define MOCK_IMPL(rv, funcname, arglist)        \
   rv funcname arglist
 #endif /* defined(TOR_UNIT_TESTS) */
 /** @} */
diff --git a/src/lib/version/git_revision.c b/src/lib/version/git_revision.c
index e87620a20c..9ee49f0c37 100644
--- a/src/lib/version/git_revision.c
+++ b/src/lib/version/git_revision.c
@@ -23,6 +23,12 @@ const char tor_git_revision[] =
 #endif
   "";
 
+/**
+ * String appended to Tor bug messages describing the Tor version.
+ *
+ * It has the form "(on Tor 0.4.3.1-alpha)" or
+ * "(on Tor 0.4.3.1-alpha git-b994397f1af193f8)"
+ **/
 const char tor_bug_suffix[] = " (on Tor " VERSION
 #ifndef COCCI
 #ifndef _MSC_VER
diff --git a/src/lib/version/version.c b/src/lib/version/version.c
index b2f25e97b5..b08d566e12 100644
--- a/src/lib/version/version.c
+++ b/src/lib/version/version.c
@@ -24,6 +24,10 @@ static const char the_short_tor_version[] =
 #endif
   "";
 
+/**
+ * Longest possible version length. We make this a constant so that we
+ * can statically allocate the_tor_version.
+ **/
 #define MAX_VERSION_LEN 128
 
 /** The version of this Tor process, possibly including git version */
diff --git a/src/lib/wallclock/approx_time.c b/src/lib/wallclock/approx_time.c
index 77eeddaf56..c3cac8b9f6 100644
--- a/src/lib/wallclock/approx_time.c
+++ b/src/lib/wallclock/approx_time.c
@@ -44,6 +44,9 @@ update_approx_time(time_t now)
 }
 #endif /* !defined(TIME_IS_FAST) */
 
+/**
+ * Initialize the "wallclock" subsystem by setting the current cached time.
+ **/
 static int
 subsys_wallclock_initialize(void)
 {
@@ -51,6 +54,9 @@ subsys_wallclock_initialize(void)
   return 0;
 }
 
+/**
+ * Subsystem function table describing the "wallclock" subsystem.
+ **/
 const subsys_fns_t sys_wallclock = {
   .name = "wallclock",
   .supported = true,