Fix most DOCDOCs remaining and/or added by redox.

svn:r17734

src/common/address.h

@@ -17,8 +17,10 @@
 #include "torint.h"
 #include "compat.h"
 
-/* DOCDOC maskbits_t */
+/** The number of bits from an address to consider while doing a masked
+ * comparison. */
 typedef uint8_t maskbits_t;
+
 struct in_addr;
 /** Holds an IPv4 or IPv6 address.  (Uses less memory than struct
  * sockaddr_storage.) */
@@ -31,20 +33,30 @@ typedef struct tor_addr_t
   } addr;
 } tor_addr_t;
 
-/* DOCDOC*/
+/** Return an IPv4 address in network order for <b>a</b>, or 0 if
+ * <b>a</b> is not an IPv4 address. */
 static INLINE uint32_t tor_addr_to_ipv4n(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_ipv4h */
+/** Return an IPv4 address in host order for <b>a</b>, or 0 if
+ * <b>a</b> is not an IPv4 address. */
 static INLINE uint32_t tor_addr_to_ipv4h(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_mapped_ipv4h */
+/* Given an IPv6 address, return its mapped IPv4 address in host order, or
+ * 0 if <b>a</b> is not an IPv6 address.
+ *
+ * (Does not check whether the address is really a mapped address */
 static INLINE uint32_t tor_addr_to_mapped_ipv4h(const tor_addr_t *a);
-/* DOCDOC tor_addr_family */
+/** Return the address family of <b>a</b>.  Possible values are:
+ * AF_INET6, AF_INET, AF_UNSPEC. */
 static INLINE sa_family_t tor_addr_family(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_in */
+/** Return an in_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not
+ * an IPv4 address. */
 static INLINE const struct in_addr *tor_addr_to_in(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_in6 */
+/** Return an in6_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not
+ * an IPv6 address. */
 static INLINE const struct in6_addr *tor_addr_to_in6(const tor_addr_t *a);
-/* DOCDOC tor_addr_eq_ipv4h */
+/** Return true iff <b>a</b> is an IPv4 address equal to the host-ordered
+ * address in <b>u</b>. */
 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);
 int tor_addr_from_sockaddr(tor_addr_t *a, const struct sockaddr *sa,
@@ -74,7 +86,7 @@ tor_addr_to_ipv4h(const tor_addr_t *a)
 static INLINE uint32_t
 tor_addr_to_mapped_ipv4h(const tor_addr_t *a)
 {
-  return ntohl(tor_addr_to_in6_addr32(a)[3]);
+  return a->family == AF_INET6 ? ntohl(tor_addr_to_in6_addr32(a)[3]) : 0;
 }
 static INLINE sa_family_t
 tor_addr_family(const tor_addr_t *a)

src/common/compat.c

@@ -1831,7 +1831,8 @@ tor_get_thread_id(void)
 #elif defined(USE_PTHREADS)
 static pthread_mutexattr_t attr_reentrant;
 static int threads_initialized = 0;
-/* DOCDOC tor_mutex_init */
+/** 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. */
 void
 tor_mutex_init(tor_mutex_t *mutex)
 {
@@ -1868,7 +1869,9 @@ tor_mutex_release(tor_mutex_t *m)
     tor_fragile_assert();
   }
 }
-/* DOCDOC tor_mutex_uninit */
+/** Clean up the mutex <b>m</b> so that it no longer uses any system
+ * resources.  Does not free <b>m</b>.  This function must only be called on
+ * mutexes from tor_mutex_init(). */
 void
 tor_mutex_uninit(tor_mutex_t *m)
 {
@@ -1894,7 +1897,7 @@ tor_get_thread_id(void)
 #endif
 
 #ifdef TOR_IS_MULTITHREADED
-/* DOCDOC tor_mutex_new */
+/** Return a newly allocated, ready-for-use mutex. */
 tor_mutex_t *
 tor_mutex_new(void)
 {
@@ -1902,7 +1905,7 @@ tor_mutex_new(void)
   tor_mutex_init(m);
   return m;
 }
-/* DOCDOC tor_mutex_free */
+/** Release all storage and system resources held by <b>m</b>. */
 void
 tor_mutex_free(tor_mutex_t *m)
 {

src/common/container.c

@@ -687,7 +687,10 @@ smartlist_uniq_digests(smartlist_t *sl)
   smartlist_uniq(sl, _compare_digests, _tor_free);
 }
 
-/* DOCDOC DEFINE_MAP_STRUCTS */
+/** Helper: Declare an entry type and a map type to implement a mapping using
+ * ht.h.  The map type will be called <b>maptype</b>.  The key part of each
+ * entry is declared using the C declaration <b>keydecl</b>.  All functions
+ * and types associated with the map get prefixed with <b>prefix</b> */
 #define DEFINE_MAP_STRUCTS(maptype, keydecl, prefix)      \
   typedef struct prefix ## entry_t {                      \
     HT_ENTRY(prefix ## entry_t) node;                     \
@@ -698,9 +701,7 @@ 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. */
@@ -1007,7 +1008,7 @@ strmap_iter_init(strmap_t *map)
   return HT_START(strmap_impl, &map->head);
 }
 
-/* DOCDOC digestmap_iter_init */
+/** Start iterating through <b>map</b>.  See strmap_iter_init() for example. */
 digestmap_iter_t *
 digestmap_iter_init(digestmap_t *map)
 {
@@ -1015,8 +1016,8 @@ digestmap_iter_init(digestmap_t *map)
   return HT_START(digestmap_impl, &map->head);
 }
 
-/** Advance the iterator <b>iter</b> for map a single step to the next entry.
- */
+/** Advance the iterator <b>iter</b> for <b>map</b> a single step to the next
+ * entry, and return its new value. */
 strmap_iter_t *
 strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
 {
@@ -1025,7 +1026,8 @@ strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
   return HT_NEXT(strmap_impl, &map->head, iter);
 }
 
-/* DOCDOC digestmap_iter_next */
+/** Advance the iterator <b>iter</b> for map a single step to the next entry,
+ * and return its new value. */
 digestmap_iter_t *
 digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter)
 {
@@ -1035,7 +1037,7 @@ digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter)
 }
 
 /** Advance the iterator <b>iter</b> a single step to the next entry, removing
- * the current entry.
+ * the current entry, and return its new value.
  */
 strmap_iter_t *
 strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
@@ -1051,7 +1053,9 @@ strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
   return iter;
 }
 
-/* DOCDOC digestmap_iter_next_rmv */
+/** Advance the iterator <b>iter</b> a single step to the next entry, removing
+ * the current entry, and return its new value.
+ */
 digestmap_iter_t *
 digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter)
 {
@@ -1065,8 +1069,8 @@ digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter)
   return iter;
 }
 
-/** Set *keyp and *valp to the current entry pointed to by iter.
- */
+/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by
+ * iter. */
 void
 strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
 {
@@ -1078,7 +1082,8 @@ strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
   *valp = (*iter)->val;
 }
 
-/* DOCDOC digestmap_iter_get */
+/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by
+ * iter. */
 void
 digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp)
 {
@@ -1090,14 +1095,16 @@ digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp)
   *valp = (*iter)->val;
 }
 
-/** Return true iff iter has advanced past the last entry of map.
- */
+/** Return true iff <b>iter</b> has advanced past the last entry of
+ * <b>map</b>. */
 int
 strmap_iter_done(strmap_iter_t *iter)
 {
   return iter == NULL;
 }
-/* DOCDOC digestmap_iter_done */
+
+/** Return true iff <b>iter</b> has advanced past the last entry of
+ * <b>map</b>. */
 int
 digestmap_iter_done(digestmap_iter_t *iter)
 {
@@ -1124,7 +1131,11 @@ strmap_free(strmap_t *map, void (*free_val)(void*))
   HT_CLEAR(strmap_impl, &map->head);
   tor_free(map);
 }
-/* DOCDOC digestmap_free */
+
+/** Remove all entries from <b>map</b>, and deallocate storage for those
+ * entries.  If free_val is provided, it is invoked on every value in
+ * <b>map</b>.
+ */
 void
 digestmap_free(digestmap_t *map, void (*free_val)(void*))
 {
@@ -1141,13 +1152,15 @@ digestmap_free(digestmap_t *map, void (*free_val)(void*))
   tor_free(map);
 }
 
-/* DOCDOC strmap_assert_ok */
+/** Fail with an assertion error if anything has gone wrong with the internal
+ * representation of <b>map</b>. */
 void
 strmap_assert_ok(const strmap_t *map)
 {
   tor_assert(!_strmap_impl_HT_REP_IS_BAD(&map->head));
 }
-/* DOCDOC digestmap_assert_ok */
+/** Fail with an assertion error if anything has gone wrong with the internal
+ * representation of <b>map</b>. */
 void
 digestmap_assert_ok(const digestmap_t *map)
 {
@@ -1161,7 +1174,7 @@ strmap_isempty(const strmap_t *map)
   return HT_EMPTY(&map->head);
 }
 
-/* DOCDOC digestmap_isempty */
+/** Return true iff <b>map</b> has no entries. */
 int
 digestmap_isempty(const digestmap_t *map)
 {
@@ -1175,7 +1188,7 @@ strmap_size(const strmap_t *map)
   return HT_SIZE(&map->head);
 }
 
-/* DOCDOC digestmap_size */
+/** Return the number of items in <b>map</b>. */
 int
 digestmap_size(const digestmap_t *map)
 {

src/common/crypto.c

@@ -2274,12 +2274,13 @@ _openssl_locking_cb(int mode, int n, const char *file, int line)
     tor_mutex_release(_openssl_mutexes[n]);
 }
 
-/* DOCDOC CRYPTO_dynlock_value */
+/** OpenSSL helper type: wraps a Tor mutex so that openssl can  */
 struct CRYPTO_dynlock_value {
   tor_mutex_t *lock;
 };
 
-/* DOCDOC _openssl_dynlock_create_cb */
+/** Openssl callback function to allocate a lock: see CRYPTO_set_dynlock_*
+ * documentation in OpenSSL's docs for more info. */
 static struct CRYPTO_dynlock_value *
 _openssl_dynlock_create_cb(const char *file, int line)
 {
@@ -2291,7 +2292,8 @@ _openssl_dynlock_create_cb(const char *file, int line)
   return v;
 }
 
-/* DOCDOC _openssl_dynlock_lock_cb */
+/** Openssl callback function to acquire or release a lock: see
+ * CRYPTO_set_dynlock_* documentation in OpenSSL's docs for more info. */
 static void
 _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v,
                          const char *file, int line)
@@ -2304,7 +2306,8 @@ _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v,
     tor_mutex_release(v->lock);
 }
 
-/* DOCDOC _openssl_dynlock_destroy_cb */
+/** Openssl callback function to free a lock: see CRYPTO_set_dynlock_*
+ * documentation in OpenSSL's docs for more info. */
 static void
 _openssl_dynlock_destroy_cb(struct CRYPTO_dynlock_value *v,
                             const char *file, int line)

src/common/crypto.h

@@ -51,13 +51,9 @@
 /** 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 */

src/common/log.c

@@ -766,7 +766,8 @@ parse_log_domain(const char *domain)
   return 0;
 }
 #if 0
-/** DOCDOC */
+/** Translate a bitmask of log domains to a string, or NULL if the bitmask
+ * is undecodable. */
 static const char *
 domain_to_string(log_domain_mask_t domain)
 {

src/common/memarea.c

@@ -85,7 +85,8 @@ alloc_chunk(size_t sz, int freelist_ok)
   }
 }
 
-/* DOCDOC chunk_free */
+/** Release <b>chunk</b> from a memarea, either by adding it to the freelist
+ * or by freeing it if the freelist is already too big. */
 static void
 chunk_free(memarea_chunk_t *chunk)
 {

src/common/util.c

@@ -1341,14 +1341,16 @@ update_approx_time(time_t now)
  */
 static int ftime_skew = 0;
 static int ftime_slop = 60;
-/* DOCDOC ftime_set_maximum_sloppiness */
+/** Set the largest amount of sloppiness we'll allow in fuzzy time
+ * comparisons. */
 void
 ftime_set_maximum_sloppiness(int seconds)
 {
   tor_assert(seconds >= 0);
   ftime_slop = seconds;
 }
-/* DOCDOC ftime_set_estimated_skew */
+/** Set the amount by which we believe our system clock to differ from
+ * real time. */
 void
 ftime_set_estimated_skew(int seconds)
 {
@@ -1362,21 +1364,21 @@ ftime_get_window(time_t now, ftime_t *ft_out)
   ft_out->latest =  now + ftime_skew + ftime_slop;
 }
 #endif
-/* DOCDOC ftime_maybe_after */
+/** Return true iff we think that <b>now</b> might be after <b>when</b>. */
 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 */
+/** Return true iff we think that <b>now</b> might be before <b>when</b>. */
 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 */
+/** Return true if we think that <b>now</b> is definitely after <b>when</b>. */
 int
 ftime_definitely_after(time_t now, time_t when)
 {
@@ -1384,7 +1386,7 @@ ftime_definitely_after(time_t now, time_t when)
    * after when. */
   return (now + ftime_skew - ftime_slop) >= when;
 }
-/* DOCDOC ftime_definitely_before */
+/** Return true if we think that <b>now</b> is definitely before <b>when</b>. */
 int
 ftime_definitely_before(time_t now, time_t when)
 {

src/or/buffers.c

@@ -549,7 +549,8 @@ buf_add_chunk_with_capacity(buf_t *buf, size_t capacity, int capped)
   return chunk;
 }
 
-/** DOCDOC */
+/** If we're using readv and writev, how many chunks are we willing to
+ * read/write at a time? */
 #define N_IOV 3
 
 /** Read up to <b>at_most</b> bytes from the socket <b>fd</b> into

src/or/connection.c

@@ -153,7 +153,8 @@ conn_state_to_string(int type, int state)
   return buf;
 }
 
-/* DOCDOC dir_connection_new */
+/** Allocate and return a new dir_connection_t, initialized as by
+ * connection_init(). */
 dir_connection_t *
 dir_connection_new(int socket_family)
 {
@@ -161,7 +162,9 @@ dir_connection_new(int socket_family)
   connection_init(time(NULL), TO_CONN(dir_conn), CONN_TYPE_DIR, socket_family);
   return dir_conn;
 }
-/* DOCDOC or_connection_new */
+
+/** Allocate and return a new or_connection_t, initialized as by
+ * connection_init(). */
 or_connection_t *
 or_connection_new(int socket_family)
 {
@@ -174,7 +177,9 @@ or_connection_new(int socket_family)
 
   return or_conn;
 }
-/* DOCDOC edge_connection_new */
+
+/** Allocate and return a new edge_connection_t, initialized as by
+ * connection_init(). */
 edge_connection_t *
 edge_connection_new(int type, int socket_family)
 {
@@ -185,7 +190,9 @@ edge_connection_new(int type, int socket_family)
     edge_conn->socks_request = tor_malloc_zero(sizeof(socks_request_t));
   return edge_conn;
 }
-/* DOCDOC control_connection_new */
+
+/** Allocate and return a new control_connection_t, initialized as by
+ * connection_init(). */
 control_connection_t *
 control_connection_new(int socket_family)
 {
@@ -196,7 +203,9 @@ control_connection_new(int socket_family)
   return control_conn;
 }
 
-/* DOCDOC connection_new */
+/** Allocate, initialize, and return a new connection_t subtype of <b>type</b>
+ * to make or receive connections of address family <b>socket_family</b>.  The
+ * type should be one of the CONN_TYPE_* constants. */
 connection_t *
 connection_new(int type, int socket_family)
 {
@@ -811,7 +820,9 @@ create_unix_sockaddr(const char *listenaddress, char **readable_address)
 };
 #endif /* HAVE_SYS_UN_H */
 
-/* DOCDOC warn_too_many_conns */
+/** Warn that an accept or a connect has failed because we're running up
+ * against our ulimit.  Rate-limit these warnings so that we don't spam
+ * the log. */
 static void
 warn_too_many_conns(void)
 {

src/or/control.c

@@ -83,13 +83,25 @@ static char authentication_cookie[AUTHENTICATION_COOKIE_LEN];
  * of this so we can respond to getinfo status/bootstrap-phase queries. */
 static char last_sent_bootstrap_message[BOOTSTRAP_MSG_LEN];
 
+/** Flag for event_format_t.  Indicates that we should use the old
+ * name format of nickname|hexdigest
+ */
 #define SHORT_NAMES 1
+/** Flag for event_format_t.  Indicates that we should use the new
+ * name format of $hexdigest[=~]nickname
+ */
 #define LONG_NAMES 2
 #define ALL_NAMES (SHORT_NAMES|LONG_NAMES)
+/** Flag for event_format_t.  Indicates that we should use the new event
+ * format where extra event fields are allowed using a NAME=VAL format. */
 #define EXTENDED_FORMAT 4
+/** Flag for event_format_t.  Indicates that we are using the old event format
+ * where extra fields aren't allowed. */
 #define NONEXTENDED_FORMAT 8
 #define ALL_FORMATS (EXTENDED_FORMAT|NONEXTENDED_FORMAT)
-/* DOCDOC event_format_t */
+
+/** Bit field of flags to select how to format a controller event.  Recognized
+ * flags are SHORT_NAMES, LONG_NAMES, EXTENDED_FORMAT, NONEXTENDED_FORMAT. */
 typedef int event_format_t;
 
 static void connection_printf_to_buf(control_connection_t *conn,

src/or/directory.c

@@ -862,18 +862,17 @@ _compare_strs(const void **a, const void **b)
   return strcmp(s1, s2);
 }
 
+#define CONDITIONAL_CONSENSUS_FPR_LEN 3
+#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
+#error "conditional consensus fingerprint length is larger than digest length"
+#endif
+
 /** Return the URL we should use for a consensus download.
  *
  * This url depends on whether or not the server we go to
  * is sufficiently new to support conditional consensus downloading,
  * i.e. GET .../consensus/<b>fpr</b>+<b>fpr</b>+<b>fpr</b>
  */
-#define CONDITIONAL_CONSENSUS_FPR_LEN 3
-#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
-#error "conditional consensus fingerprint length is larger than digest length"
-#endif
-
-/* DOCDOC directory_get_consensus_url */
 static char *
 directory_get_consensus_url(int supports_conditional_consensus)
 {
@@ -2195,7 +2194,10 @@ typedef struct request_t {
  * of request.  Maps from request type to pointer to request_t. */
 static strmap_t *request_map = NULL;
 
-/* DOCDOC note_client_request */
+/** Record that a client request of <b>purpose</b> was made, and that
+ * <b>bytes</b> bytes of possibly <b>compressed</b> data were sent/received.
+ * Used to keep track of how much we've up/downloaded in what kind of
+ * request. */
 static void
 note_client_request(int purpose, int compressed, size_t bytes)
 {

src/or/dirserv.c

@@ -1587,7 +1587,8 @@ dirserv_get_runningrouters(void)
                          "v1 network status list", V1_AUTHORITY);
 }
 
-/* DOCDOC */
+/** Return the latest downloaded consensus networkstatus in encoded, signed,
+ * optionally compressed format, suitable for sending to clients. */
 cached_dir_t *
 dirserv_get_consensus(void)
 {

src/or/dirvote.c

@@ -219,7 +219,9 @@ get_voter(const networkstatus_t *vote)
   return smartlist_get(vote->voters, 0);
 }
 
-/* DOCDOC dir_src_ent_t */
+/** Temporary structure used in constructing a list of dir-source entries
+ * for a consensus.  One of these is generated for every vote, and one more
+ * for every legacy key in each vote. */
 typedef struct dir_src_ent_t {
   networkstatus_t *v;
   const char *digest;
@@ -236,7 +238,9 @@ _compare_votes_by_authority_id(const void **_a, const void **_b)
                 get_voter(b)->identity_digest, DIGEST_LEN);
 }
 
-/* DOCDOC _compare_dir_src_ents_by_authority_id */
+/** Helper: Compare the dir_src_ent_ts in *<b>_a</b> and *<b>_b</b> by
+ * their identity digests, and return -1, 0, or 1 depending on their
+ * ordering */
 static int
 _compare_dir_src_ents_by_authority_id(const void **_a, const void **_b)
 {

src/or/dns.c

@@ -186,9 +186,10 @@ evdns_log_cb(int warn, const char *msg)
   log(severity, LD_EXIT, "eventdns: %s", msg);
 }
 
-/* DOCDOC randfn */
+/** Helper: passed to eventdns.c as a callback so it can generate random
+ * numbers for transaction IDs and 0x20-hack coding. */
 static void
-randfn(char *b, size_t n)
+_dns_randfn(char *b, size_t n)
 {
   crypto_rand(b,n);
 }
@@ -198,7 +199,7 @@ int
 dns_init(void)
 {
   init_cache_map();
-  evdns_set_random_bytes_fn(randfn);
+  evdns_set_random_bytes_fn(_dns_randfn);
   if (get_options()->ServerDNSRandomizeCase)
     evdns_set_option("randomize-case", "1", DNS_OPTIONS_ALL);
   else

src/or/geoip.c

@@ -438,7 +438,8 @@ _c_hist_compare(const void **_a, const void **_b)
  * are willing to talk about it? */
 #define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
 
-/* DOCDOC round_to_next_multiple_of */
+/** Return the lowest x such that x is at least <b>number</b>, and x modulo
+ * <b>divisor</b> == 0. */
 static INLINE unsigned
 round_to_next_multiple_of(unsigned number, unsigned divisor)
 {
@@ -589,7 +590,7 @@ geoip_get_request_history(time_t now, geoip_client_action_t action)
   return result;
 }
 
-/* DOCDOC dump_geoip_stats */
+/** Store all our geoip statistics into $DATADIR/geoip-stats. */
 void
 dump_geoip_stats(void)
 {

src/or/main.c

@@ -1902,14 +1902,14 @@ try_locking(or_options_t *options, int err_if_locked)
   }
 }
 
-/* DOCDOC have_lockfile */
+/** Return true iff we've successfully acquired the lock file. */
 int
 have_lockfile(void)
 {
   return lockfile != NULL;
 }
 
-/* DOCDOC release_lockfile */
+/** If we have successfully acquired the lock file, release it. */
 void
 release_lockfile(void)
 {

src/or/policies.c

@@ -235,7 +235,10 @@ addr_policy_permits_tor_addr(const tor_addr_t *addr, uint16_t port,
   }
 }
 
-/* DOCDOC XXXX deprecate when possible. */
+/** Return true iff <b> policy</b> (possibly NULL) will allow a connection to
+ * <b>addr</b>:<b>port</b>.  <b>addr</b> is an IPv4 address given in host
+ * order. */
+/* XXXX deprecate when possible. */
 static int
 addr_policy_permits_address(uint32_t addr, uint16_t port,
                             smartlist_t *policy)
@@ -254,7 +257,8 @@ fascist_firewall_allows_address_or(const tor_addr_t *addr, uint16_t port)
                                      reachable_or_addr_policy);
 }
 
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make an OR connection to
+ * <b>ri</b>. */
 int
 fascist_firewall_allows_or(routerinfo_t *ri)
 {
@@ -552,7 +556,8 @@ addr_policy_get_canonical_entry(addr_policy_t *e)
   return found->policy;
 }
 
-/** DOCDOC */
+/** As compare_to_addr_to_addr_policy, but instead of a tor_addr_t, takes
+ * in host order. */
 addr_policy_result_t
 compare_addr_to_addr_policy(uint32_t addr, uint16_t port, smartlist_t *policy)
 {

src/or/relay.c

@@ -1470,7 +1470,9 @@ packed_cell_alloc(void)
   ++total_cells_allocated;
   return mp_pool_get(cell_pool);
 }