Add DOCDOC comments for all undocumented functions. Add missing *s to other comments so that they will get recognized as doxygen.

svn:r17729

8 files changed, 45 insertions, 3 deletions

diff --git a/src/common/address.h b/src/common/address.h
index fa2ac1b5bc..4a6e9859ef 100644
--- a/src/common/address.h
+++ b/src/common/address.h
@@ -17,6 +17,7 @@
 #include "torint.h"
 #include "compat.h"
 
+/* DOCDOC maskbits_t */
 typedef uint8_t maskbits_t;
 struct in_addr;
 /** Holds an IPv4 or IPv6 address.  (Uses less memory than struct
@@ -32,11 +33,17 @@ typedef struct tor_addr_t
 
 /* DOCDOC*/
 static INLINE uint32_t tor_addr_to_ipv4n(const tor_addr_t *a);
+/* DOCDOC tor_addr_to_ipv4h */
 static INLINE uint32_t tor_addr_to_ipv4h(const tor_addr_t *a);
+/* DOCDOC tor_addr_to_mapped_ipv4h */
 static INLINE uint32_t tor_addr_to_mapped_ipv4h(const tor_addr_t *a);
+/* DOCDOC tor_addr_family */
 static INLINE sa_family_t tor_addr_family(const tor_addr_t *a);
+/* DOCDOC tor_addr_to_in */
 static INLINE const struct in_addr *tor_addr_to_in(const tor_addr_t *a);
+/* DOCDOC tor_addr_to_in6 */
 static INLINE const struct in6_addr *tor_addr_to_in6(const tor_addr_t *a);
+/* DOCDOC tor_addr_eq_ipv4h */
 static INLINE int tor_addr_eq_ipv4h(const tor_addr_t *a, uint32_t u);
 socklen_t tor_addr_to_sockaddr(const tor_addr_t *a, uint16_t port,
                                struct sockaddr *sa_out, socklen_t len);
@@ -153,7 +160,8 @@ int parse_addr_and_port_range(const char *s, uint32_t *addr_out,
                               uint16_t *port_max_out);
 int addr_mask_get_bits(uint32_t mask);
 int addr_mask_cmp_bits(uint32_t a1, uint32_t a2, maskbits_t bits);
-#define INET_NTOA_BUF_LEN 16 /* 255.255.255.255 */
+/** Length of a buffer to allocate to hold the results of tor_inet_ntoa.*/
+#define INET_NTOA_BUF_LEN 16
 int tor_inet_ntoa(const struct in_addr *in, char *buf, size_t buf_len);
 char *tor_dup_ip(uint32_t addr) ATTR_MALLOC;
 int get_interface_address(int severity, uint32_t *addr);
diff --git a/src/common/compat.c b/src/common/compat.c
index e506a2b975..d75cab5571 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -1831,6 +1831,7 @@ tor_get_thread_id(void)
 #elif defined(USE_PTHREADS)
 static pthread_mutexattr_t attr_reentrant;
 static int threads_initialized = 0;
+/* DOCDOC tor_mutex_init */
 void
 tor_mutex_init(tor_mutex_t *mutex)
 {
@@ -1867,6 +1868,7 @@ tor_mutex_release(tor_mutex_t *m)
     tor_fragile_assert();
   }
 }
+/* DOCDOC tor_mutex_uninit */
 void
 tor_mutex_uninit(tor_mutex_t *m)
 {
@@ -1892,6 +1894,7 @@ tor_get_thread_id(void)
 #endif
 
 #ifdef TOR_IS_MULTITHREADED
+/* DOCDOC tor_mutex_new */
 tor_mutex_t *
 tor_mutex_new(void)
 {
@@ -1899,6 +1902,7 @@ tor_mutex_new(void)
   tor_mutex_init(m);
   return m;
 }
+/* DOCDOC tor_mutex_free */
 void
 tor_mutex_free(tor_mutex_t *m)
 {
diff --git a/src/common/container.c b/src/common/container.c
index 060615d1c3..2cf45f1467 100644
--- a/src/common/container.c
+++ b/src/common/container.c
@@ -687,6 +687,7 @@ smartlist_uniq_digests(smartlist_t *sl)
   smartlist_uniq(sl, _compare_digests, _tor_free);
 }
 
+/* DOCDOC DEFINE_MAP_STRUCTS */
 #define DEFINE_MAP_STRUCTS(maptype, keydecl, prefix)      \
   typedef struct prefix ## entry_t {                      \
     HT_ENTRY(prefix ## entry_t) node;                     \
@@ -697,7 +698,9 @@ smartlist_uniq_digests(smartlist_t *sl)
     HT_HEAD(prefix ## impl, prefix ## entry_t) head;      \
   }
 
+/* DOCDOC DEFINE_MAP_STRUCTS */
 DEFINE_MAP_STRUCTS(strmap_t, char *key, strmap_);
+/* DOCDOC DEFINE_MAP_STRUCTS */
 DEFINE_MAP_STRUCTS(digestmap_t, char key[DIGEST_LEN], digestmap_);
 
 /** Helper: compare strmap_entry_t objects by key value. */
@@ -1004,6 +1007,7 @@ strmap_iter_init(strmap_t *map)
   return HT_START(strmap_impl, &map->head);
 }
 
+/* DOCDOC digestmap_iter_init */
 digestmap_iter_t *
 digestmap_iter_init(digestmap_t *map)
 {
@@ -1021,6 +1025,7 @@ strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
   return HT_NEXT(strmap_impl, &map->head, iter);
 }
 
+/* DOCDOC digestmap_iter_next */
 digestmap_iter_t *
 digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter)
 {
@@ -1046,6 +1051,7 @@ strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
   return iter;
 }
 
+/* DOCDOC digestmap_iter_next_rmv */
 digestmap_iter_t *
 digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter)
 {
@@ -1072,6 +1078,7 @@ strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
   *valp = (*iter)->val;
 }
 
+/* DOCDOC digestmap_iter_get */
 void
 digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp)
 {
@@ -1090,6 +1097,7 @@ strmap_iter_done(strmap_iter_t *iter)
 {
   return iter == NULL;
 }
+/* DOCDOC digestmap_iter_done */
 int
 digestmap_iter_done(digestmap_iter_t *iter)
 {
@@ -1116,6 +1124,7 @@ strmap_free(strmap_t *map, void (*free_val)(void*))
   HT_CLEAR(strmap_impl, &map->head);
   tor_free(map);
 }
+/* DOCDOC digestmap_free */
 void
 digestmap_free(digestmap_t *map, void (*free_val)(void*))
 {
@@ -1132,11 +1141,13 @@ digestmap_free(digestmap_t *map, void (*free_val)(void*))
   tor_free(map);
 }
 
+/* DOCDOC strmap_assert_ok */
 void
 strmap_assert_ok(const strmap_t *map)
 {
   tor_assert(!_strmap_impl_HT_REP_IS_BAD(&map->head));
 }
+/* DOCDOC digestmap_assert_ok */
 void
 digestmap_assert_ok(const digestmap_t *map)
 {
@@ -1150,6 +1161,7 @@ strmap_isempty(const strmap_t *map)
   return HT_EMPTY(&map->head);
 }
 
+/* DOCDOC digestmap_isempty */
 int
 digestmap_isempty(const digestmap_t *map)
 {
@@ -1163,6 +1175,7 @@ strmap_size(const strmap_t *map)
   return HT_SIZE(&map->head);
 }
 
+/* DOCDOC digestmap_size */
 int
 digestmap_size(const digestmap_t *map)
 {
diff --git a/src/common/crypto.c b/src/common/crypto.c
index fdccfe1d7b..228656cf46 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -261,6 +261,7 @@ _crypto_new_pk_env_evp_pkey(EVP_PKEY *pkey)
   return _crypto_new_pk_env_rsa(rsa);
 }
 
+/* DOCDOC _crypto_pk_env_get_rsa */
 RSA *
 _crypto_pk_env_get_rsa(crypto_pk_env_t *env)
 {
@@ -2273,10 +2274,12 @@ _openssl_locking_cb(int mode, int n, const char *file, int line)
     tor_mutex_release(_openssl_mutexes[n]);
 }
 
+/* DOCDOC CRYPTO_dynlock_value */
 struct CRYPTO_dynlock_value {
   tor_mutex_t *lock;
 };
 
+/* DOCDOC _openssl_dynlock_create_cb */
 static struct CRYPTO_dynlock_value *
 _openssl_dynlock_create_cb(const char *file, int line)
 {
@@ -2288,6 +2291,7 @@ _openssl_dynlock_create_cb(const char *file, int line)
   return v;
 }
 
+/* DOCDOC _openssl_dynlock_lock_cb */
 static void
 _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v,
                          const char *file, int line)
@@ -2300,6 +2304,7 @@ _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v,
     tor_mutex_release(v->lock);
 }
 
+/* DOCDOC _openssl_dynlock_destroy_cb */
 static void
 _openssl_dynlock_destroy_cb(struct CRYPTO_dynlock_value *v,
                             const char *file, int line)
diff --git a/src/common/crypto.h b/src/common/crypto.h
index 86dfa88076..6e6163c8cb 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -51,9 +51,13 @@
 /** Length of hex encoding of SHA1 digest, not including final NUL. */
 #define HEX_DIGEST_LEN 40
 
+/* DOCDOC crypto_pk_env_t */
 typedef struct crypto_pk_env_t crypto_pk_env_t;
+/* DOCDOC crypto_cipher_env_t */
 typedef struct crypto_cipher_env_t crypto_cipher_env_t;
+/* DOCDOC crypto_digest_env_t */
 typedef struct crypto_digest_env_t crypto_digest_env_t;
+/* DOCDOC crypto_dh_env_t */
 typedef struct crypto_dh_env_t crypto_dh_env_t;
 
 /* global state */
diff --git a/src/common/memarea.c b/src/common/memarea.c
index 4257c4552c..5c565cebe7 100644
--- a/src/common/memarea.c
+++ b/src/common/memarea.c
@@ -26,7 +26,7 @@
 #error "void* is neither 4 nor 8 bytes long. I don't know how to align stuff."
 #endif
 
-/* Increment <b>ptr</b> until it is aligned to MEMAREA_ALIGN. */
+/** Increment <b>ptr</b> until it is aligned to MEMAREA_ALIGN. */
 static INLINE void *
 realign_pointer(void *ptr)
 {
@@ -85,6 +85,7 @@ alloc_chunk(size_t sz, int freelist_ok)
   }
 }
 
+/* DOCDOC chunk_free */
 static void
 chunk_free(memarea_chunk_t *chunk)
 {
diff --git a/src/common/torgzip.h b/src/common/torgzip.h
index 057f9708d3..8bcb8fd82a 100644
--- a/src/common/torgzip.h
+++ b/src/common/torgzip.h
@@ -41,6 +41,7 @@ compress_method_t detect_compression_method(const char *in, size_t in_len);
 typedef enum {
   TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
 } tor_zlib_output_t;
+/** Internal state for an incremental zlib compression/decompression. */
 typedef struct tor_zlib_state_t tor_zlib_state_t;
 tor_zlib_state_t *tor_zlib_new(int compress, compress_method_t method);
 
diff --git a/src/common/util.c b/src/common/util.c
index 659766a4ed..d40de03ceb 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -1341,12 +1341,14 @@ update_approx_time(time_t now)
  */
 static int ftime_skew = 0;
 static int ftime_slop = 60;
+/* DOCDOC ftime_set_maximum_sloppiness */
 void
 ftime_set_maximum_sloppiness(int seconds)
 {
   tor_assert(seconds >= 0);
   ftime_slop = seconds;
 }
+/* DOCDOC ftime_set_estimated_skew */
 void
 ftime_set_estimated_skew(int seconds)
 {
@@ -1360,18 +1362,21 @@ ftime_get_window(time_t now, ftime_t *ft_out)
   ft_out->latest =  now + ftime_skew + ftime_slop;
 }
 #endif
+/* DOCDOC ftime_maybe_after */
 int
 ftime_maybe_after(time_t now, time_t when)
 {
   /* It may be after when iff the latest possible current time is after when */
   return (now + ftime_skew + ftime_slop) >= when;
 }
+/* DOCDOC ftime_maybe_before */
 int
 ftime_maybe_before(time_t now, time_t when)
 {
   /* It may be before when iff the earliest possible current time is before */
   return (now + ftime_skew - ftime_slop) < when;
 }
+/* DOCDOC ftime_definitely_after */
 int
 ftime_definitely_after(time_t now, time_t when)
 {
@@ -1379,6 +1384,7 @@ ftime_definitely_after(time_t now, time_t when)
    * after when. */
   return (now + ftime_skew - ftime_slop) >= when;
 }
+/* DOCDOC ftime_definitely_before */
 int
 ftime_definitely_before(time_t now, time_t when)
 {
@@ -1941,7 +1947,7 @@ read_file_to_str(const char *filename, int flags, struct stat *stat_out)
 
 #define TOR_ISODIGIT(c) ('0' <= (c) && (c) <= '7')
 
-/* Given a c-style double-quoted escaped string in <b>s</b>, extract and
+/** Given a c-style double-quoted escaped string in <b>s</b>, extract and
  * decode its contents into a newly allocated string.  On success, assign this
  * string to *<b>result</b>, assign its length to <b>size_out</b> (if
  * provided), and return a pointer to the position in <b>s</b> immediately