Resolve many DOCDOCs.

svn:r17662

src/common/address.c

@@ -630,7 +630,7 @@ tor_addr_from_ipv6_bytes(tor_addr_t *dest, const char *ipv6_bytes)
   memcpy(dest->addr.in6_addr.s6_addr, ipv6_bytes, 16);
 }
 
-/** DOCDOC */
+/** Set <b>dest</b> equal to the IPv6 address in the in6_addr <b>in6</b>. */
 void
 tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6)
 {

src/common/log.c

@@ -53,7 +53,8 @@ typedef struct logfile_t {
   int is_temporary; /**< Boolean: close after initializing logging subsystem.*/
   int is_syslog; /**< Boolean: send messages to syslog. */
   log_callback callback; /**< If not NULL, send messages to this function. */
-  log_severity_list_t *severities; /**< DOCDOC */
+  log_severity_list_t *severities; /**< Which severity of messages should we
+                                    * log for each log domain? */
 } logfile_t;
 
 static void log_free(logfile_t *victim);
@@ -415,7 +416,7 @@ _log_err(log_domain_mask_t domain, const char *format, ...)
 }
 #endif
 
-/** DOCDOC */
+/** Free all storage held by <b>victim</b>. */
 static void
 log_free(logfile_t *victim)
 {
@@ -730,14 +731,17 @@ log_level_to_string(int level)
   return sev_to_string(level);
 }
 
-/** DOCDOC */
+/** NULL-terminated array of names for log domains such that domain_list[dom]
+ * is a description of <b>dom</b>. */
 static const char *domain_list[] = {
   "GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM",
   "HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV",
   "OR", "EDGE", "ACCT", "HIST", NULL
 };
 
-/** DOCDOC */
+/** Return the log domain for which <b>domain</b> is the name, or 0 if there
+ * is no such name. */
+/*XXXX021 0 could mean "no such domain" or LD_GENERAL.  Fix that. */
 static log_domain_mask_t
 parse_log_domain(const char *domain)
 {

src/common/memarea.c

@@ -138,7 +138,7 @@ memarea_clear(memarea_t *area)
   area->first->next_mem = area->first->u.mem;
 }
 
-/** DOCDOC */
+/** Remove all unused memarea chunks from the internal freelist. */
 void
 memarea_clear_freelist(void)
 {

src/common/tortls.c

@@ -1442,7 +1442,11 @@ tor_tls_used_v1_handshake(tor_tls_t *tls)
   return 1;
 }
 
-/** DOCDOC */
+/** Examine the amount of memory used and available for buffers in <b>tls</b>.
+ * Set *<b>rbuf_capacity</b> to the amount of storage allocated for the read
+ * buffer and *<b>rbuf_bytes</b> to the amount actually used.
+ * Set *<b>wbuf_capacity</b> to the amount of storage allocated for the write
+ * buffer and *<b>wbuf_bytes</b> to the amount actually used. */
 void
 tor_tls_get_buffer_sizes(tor_tls_t *tls,
                          int *rbuf_capacity, int *rbuf_bytes,

src/common/tortls.h

@@ -33,7 +33,8 @@ typedef struct tor_tls_t tor_tls_t;
 #define TOR_TLS_WANTWRITE          -1
 #define TOR_TLS_DONE                0
 
-/** DOCDOC XXXX021 also rename me. */
+/** Collection of case statements for all TLS errors that are not due to
+ * underlying IO failure. */
 #define CASE_TOR_TLS_ERROR_ANY_NONIO            \
   case TOR_TLS_ERROR_MISC:                      \
   case TOR_TLS_ERROR_CONNREFUSED:               \

src/or/config.c

@@ -1191,7 +1191,8 @@ options_act_reversible(or_options_t *old_options, char **msg)
   return r;
 }
 
-/** DOCDOC */
+/** If we need to have a GEOIP ip-to-country map to run with our configured
+ * options, return 1 and set *<b>reason_out</b> to a description of why. */
 int
 options_need_geoip_info(or_options_t *options, const char **reason_out)
 {

src/or/connection_edge.c

@@ -1361,6 +1361,11 @@ consider_plaintext_ports(edge_connection_t *conn, uint16_t port)
   return 0;
 }
 
+/** How many times do we try connecting with an exit configured via
+ * TrackHostExits before concluding that it won't work any more and trying a
+ * different one? */
+#define TRACKHOSTEXITS_RETRIES 5
+
 /** 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
@@ -1500,8 +1505,6 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn,
     if (s) {
       if (s[1] != '\0') {
         conn->chosen_exit_name = tor_strdup(s+1);
-/* DOCDOC */
-#define TRACKHOSTEXITS_RETRIES 5
         if (remapped_to_exit) /* 5 tries before it expires the addressmap */
           conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES;
         *s = 0;

src/or/directory.c

@@ -2179,13 +2179,13 @@ write_http_response_header(dir_connection_t *conn, ssize_t length,
 }
 
 #ifdef INSTRUMENT_DOWNLOADS
-/** Map used to keep track of how much data we've up/downloaded in what kind
- * of request.  Maps from request type to pointer to uint64_t. */
 typedef struct request_t {
-  uint64_t bytes;
+  uint64_t bytes; /**< How many bytes have we transferred? */
-  uint64_t count;
+  uint64_t count; /**< How many requests have we made? */
 } request_t;
 
+/** Map used to keep track of how much data we've up/downloaded in what kind
+ * of request.  Maps from request type to pointer to request_t. */
 static strmap_t *request_map = NULL;
 
 static void
@@ -2222,7 +2222,7 @@ note_client_request(int purpose, int compressed, size_t bytes)
   tor_free(key);
 }
 
-/** DOCDOC */
+/** Helper: initialize the request map to instrument downloads. */
 static void
 ensure_request_map_initialized(void)
 {
@@ -3394,6 +3394,8 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code,
    * every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */
 }
 
+/** Helper.  Compare two fp_pair_t objects, and return -1, 0, or 1 as
+ * appropriate. */
 static int
 _compare_pairs(const void **a, const void **b)
 {
@@ -3405,7 +3407,10 @@ _compare_pairs(const void **a, const void **b)
     return memcmp(fp1->second, fp2->second, DIGEST_LEN);
 }
 
-/** DOCDOC */
+/** Divide a string <b>res</b> of the form FP1-FP2+FP3-FP4...[.z], where each
+ * FP is a hex-encoded fingerprint, into a sequence of distinct sorted
+ * fp_pair_t. Skip malformed pairs. On success, return 0 and add those
+ * fp_pair_t into <b>pairs_out</b>.  On failure, return -1. */
 int
 dir_split_resource_into_fingerprint_pairs(const char *res,
                                           smartlist_t *pairs_out)

src/or/dns.c

@@ -229,7 +229,8 @@ dns_reset(void)
   return 0;
 }
 
-/**DOCDOC*/
+/** Return true iff the most recent attempt to initialize the DNS subsystem
+ * failed. */
 int
 has_dns_init_failed(void)
 {

src/or/eventdns.c

@@ -307,7 +307,7 @@ static int global_max_retransmits = 3;	/* number of times we'll retransmit a req
 /* number of timeouts in a row before we consider this server to be down */
 static int global_max_nameserver_timeout = 3;
 
-/* DOCDOC */
+/* true iff we should use the 0x20 hack. */
 static int global_randomize_case = 1;
 
 /* These are the timeout values for nameservers. If we find a nameserver is down */

src/or/geoip.c

@@ -23,10 +23,12 @@ typedef struct geoip_entry_t {
   intptr_t country; /**< An index into geoip_countries */
 } geoip_entry_t;
 
-/** DOCDOC */
+/** For how many periods should we remember per-country request history? */
 #define REQUEST_HIST_LEN 3
+/** How long are the periods for which we should remember request history? */
 #define REQUEST_HIST_PERIOD (8*60*60)
 
+/** A per-country record for GeoIP request history */
 typedef struct geoip_country_t {
   char countrycode[3];
   uint32_t n_v2_ns_requests[REQUEST_HIST_LEN];
@@ -269,8 +271,10 @@ static HT_HEAD(clientmap, clientmap_entry_t) client_history =
 /** Time at which we started tracking client IP history. */
 static time_t client_history_starts = 0;
 
-/** DOCDOC */
+/** When did the current period of checking per-country request history
+ * start? */
 static time_t current_request_period_starts = 0;
+/** How many older request periods are we remembering? */
 static int n_old_request_periods = 0;
 
 /** Hashtable helper: compute a hash of a clientmap_entry_t. */
@@ -312,7 +316,7 @@ geoip_note_client_seen(geoip_client_action_t action,
 #endif
   }
 
-  /* DOCDOC */
+  /* Rotate the current request period. */
   while (current_request_period_starts + REQUEST_HIST_PERIOD < now) {
     if (!geoip_countries)
       geoip_countries = smartlist_create();
@@ -430,7 +434,8 @@ _c_hist_compare(const void **_a, const void **_b)
     return strcmp(a->country, b->country);
 }
 
-/*DOCDOC*/
+/** How long do we have to have observed per-country request history before we
+ * are willing to talk about it? */
 #define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
 
 static INLINE unsigned
@@ -529,7 +534,9 @@ geoip_get_client_history(time_t now, geoip_client_action_t action)
   return result;
 }
 
-/**DOCDOC*/
+/** Return a newly allocated string holding the per-country request history
+ * for <b>action</b> in a format suitable for an extra-info document, or NULL
+ * on failure. */
 char *
 geoip_get_request_history(time_t now, geoip_client_action_t action)
 {

src/or/relay.c

@@ -1844,7 +1844,13 @@ append_cell_to_circuit_queue(circuit_t *circ, or_connection_t *orconn,
   }
 }
 
-/** DOCDOC */
+/** Append an encoded value of <b>addr<b> to <b>payload_out</b>, which must
+ * have at least 18 bytes of free space.  The encoding is, as specified in
+ * tor-spec.txt:
+ *   RESOLVED_TYPE_IPV4 or RESOLVED_TYPE_IPV6  [1 byte]
+ *   LENGTH                                    [1 byte]
+ *   ADDRESS                                   [length bytes]
+ * Return the number of bytes added, or -1 on error */
 int
 append_address_to_payload(char *payload_out, const tor_addr_t *addr)
 {
@@ -1867,7 +1873,10 @@ append_address_to_payload(char *payload_out, const tor_addr_t *addr)
   }
 }
 
-/** DODOC */
+/** Given <b>payload_len</b> bytes at <b>payload</b>, starting with an address
+ * encoded as by append_address_to_payload(), try to decode the address into
+ * *<b>addr_out</b>.  Return the next byte in the payload after the address on
+ * success, or NULL on failure. */
 const char *
 decode_address_from_payload(tor_addr_t *addr_out, const char *payload,
                             int payload_len)

src/or/rephist.c

@@ -777,7 +777,8 @@ rep_hist_record_mtbf_data(void)
   return -1;
 }
 
-/** DOCDOC */
+/** Format the current tracked status of the router in <b>hist</b> at time
+ * <b>now</b> for analysis; return it in a newly allocated string. */
 static char *
 rep_hist_format_router_status(or_history_t *hist, time_t now)
 {
@@ -821,12 +822,17 @@ rep_hist_format_router_status(or_history_t *hist, time_t now)
   return tor_strdup(buf);
 }
 
-/* DOCDOC */
+/** The last stability analysis document that we created, or NULL if we never
+ * have created one. */
 static char *last_stability_doc = NULL;
+/** The last time we created a stability analysis document, or 0 if we never
+ * have created one. */
 static time_t built_last_stability_doc_at = 0;
+/** Shortest allowable time between building two stability documents. */
 #define MAX_STABILITY_DOC_BUILD_RATE (3*60)
 
-/* DOCDOC */
+/** Return a pointer to a NUL-terminated document describing our view of the
+ * stability of the routers we've been tracking.  Return NULL on failure. */
 const char *
 rep_hist_get_router_stability_doc(time_t now)
 {

src/or/routerlist.c

@@ -4808,12 +4808,18 @@ struct routerset_t {
    * a router belongs to the set if it is _rejected_ by this policy. */
   smartlist_t *policies;
 
-  /** DOCDOC */
+  /** A human-readable description of what this routerset is for.  Used in
+   * log messages. */
   char *description;
 
-  /** DOCDOC */
+  /** A list of the country codes in this set. */
   smartlist_t *country_names;
+  /** Total number of countries we knew about when we built <b>countries</b>. */
   int n_countries;
+  /** Bit array mapping the return value of geoip_get_country() to 1 iff the
+   * country is a member of this routerset.  Note that we MUST call
+   * routerset_refresh_countries() whenever the geoip country list is
+   * reloaded. */
   bitarray_t *countries;
 };
 
@@ -4830,7 +4836,8 @@ routerset_new(void)
   return result;
 }
 
-/** DOCDOC */
+/** If <b>c</b> is a country code in the form {cc}, return a newly allocated
+ * string holding the "cc" part.  Else, return NULL. */
 static char *
 routerset_get_countryname(const char *c)
 {
@@ -4981,14 +4988,15 @@ routerset_is_list(const routerset_t *set)
     smartlist_len(set->policies) == 0;
 }
 
-/** DOCDOC */
+/** Return true iff we need a GeoIP IP-to-country database to make sense of
+ * <b>set</b>. */
 int
 routerset_needs_geoip(const routerset_t *set)
 {
   return set && smartlist_len(set->country_names);
 }
 
-/** DOCDOC */
+/** Return true iff there are no entries in <b>set</b>. */
 static int
 routerset_is_empty(const routerset_t *set)
 {
@@ -4996,8 +5004,12 @@ routerset_is_empty(const routerset_t *set)
 }
 
 /** Helper.  Return true iff <b>set</b> contains a router based on the other
- * provided fields.  Return higher values for more specific subentries.
+ * provided fields.  Return higher values for more specific subentries: a
- (If country is -1, then we take the country from addr.) */
+ * single router is more specific than an address range of routers, which is
+ * more specific in turn than a country code.
+ *
+ * (If country is -1, then we take the country
+ * from addr.) */
 static int
 routerset_contains(const routerset_t *set, const tor_addr_t *addr,
                    uint16_t orport,
@@ -5102,9 +5114,10 @@ routerset_get_all_routers(smartlist_t *out, const routerset_t *routerset,
   }
 }
 
-/** Add to <b>target</b> every node from <b>source</b> that is in
+/** Add to <b>target</b> every routerinfo_t from <b>source</b> that is in
- * <b>include</b> not excluded in a more specific fashion by
+ * <b>include</b>, but not excluded in a more specific fashion by
- * <b>exclude</b>. DOCDOC */
+ * <b>exclude</b>.  If <b>running_only</b>, only include running routers.
+ */
 void
 routersets_get_disjunction(smartlist_t *target,
                            const smartlist_t *source,
@@ -5217,14 +5230,15 @@ routerset_free(routerset_t *routerset)
   tor_free(routerset);
 }
 
-/** DOCDOC */
+/** Refresh the country code of <b>ri</b>.  This function MUST be called on
+ * each router when the GeoIP database is reloaded, and on all new routers. */
 void
 routerinfo_set_country(routerinfo_t *ri)
 {
   ri->country = geoip_get_country_by_ip(ri->addr);
 }
 
-/** DOCDOC */
+/** Set the country code of all routers in the routerlist. */
 void
 routerlist_refresh_countries(void)
 {