Add more missing documentation, and correct an error in container.c documentation: Don't introduce two parameters called n when you're calling an algorithm O(n).

svn:r17783

src/common/container.c

@@ -1199,7 +1199,7 @@ digestmap_size(const digestmap_t *map)
  * function for an array of type <b>elt_t</b>*.
  *
  * NOTE: The implementation kind of sucks: It's O(n log n), whereas finding
- * the nth element of a list can be done in O(n).  Then again, this
+ * the kth element of an n-element list can be done in O(n).  Then again, this
  * implementation is not in critical path, and it is obviously correct. */
 #define IMPLEMENT_ORDER_FUNC(funcname, elt_t)                   \
   static int                                                    \

src/or/connection.c

@@ -34,9 +34,11 @@ static int connection_process_inbuf(connection_t *conn, int package_partial);
 static void client_check_address_changed(int sock);
 static void set_constrained_socket_buffers(int sock, int size);
 
-/* DOCDOC last_interface_ip */
+/** The last IPv4 address that our network interface seemed to have been
+ * binding to, in host order.  We use this to detect when our IP changes. */
 static uint32_t last_interface_ip = 0;
-/* DOCDOC outgoing_addrs */
+/** A list of uint32_ts for addresses we've used in outgoing connections.
+ * Used to detect IP address changes. */
 static smartlist_t *outgoing_addrs = NULL;
 
 /**************************************************************/

src/or/dirserv.c

@@ -1646,25 +1646,30 @@ should_generate_v2_networkstatus(void)
  * dirserv_compute_performance_thresholds, and used by
  * generate_v2_networkstatus */
 
-/* DOCDOC stable_uptime */
+/** Any router with an uptime of at least this value is stable. */
 static uint32_t stable_uptime = 0; /* start at a safe value */
-/* DOCDOC stable_mtbf */
+/** Any router with an mtbf of at least this value is stable. */
 static double stable_mtbf = 0.0;
-/* DOCDOC enough_mtbf_info */
+/** If true, we have measured enough mtbf info to look at stable_mtbf rather
+ * than stable_uptime. */
 static int enough_mtbf_info = 0;
-/* DOCDOC guard_wfu */
+/** Any router with a weighted fractional uptime of at least this much might
+ * be good as a guard. */
 static double guard_wfu = 0.0;
-/* DOCDOC guard_tk */
+/** Don't call a router a guard unless we've known about it for at least this
+ * many seconds. */
 static long guard_tk = 0;
-/* DOCDOC fast_bandwidth */
+/** Any router with a bandwidth at least this high is "Fast" */
 static uint32_t fast_bandwidth = 0;
-/* DOCDOC guard_bandwidth_including_exits */
+/** If exits can be guards, then all guards must have a bandwidth this
+ * high. */
 static uint32_t guard_bandwidth_including_exits = 0;
-/* DOCDOC guard_bandwidth_excluding_exits */
+/** If exits can't be guards, then all guards must have a bandwidth this
+ * high. */
 static uint32_t guard_bandwidth_excluding_exits = 0;
-/* DOCDOC total_bandwidth */
+/** Total bandwidth of all the routers we're considering. */
 static uint64_t total_bandwidth = 0;
-/* DOCDOC total_exit_bandwidth */
+/** Total bandwidth of all the exit routers we're considering. */
 static uint64_t total_exit_bandwidth = 0;
 
 /** Helper: estimate the uptime of a router given its stated uptime and the

src/or/networkstatus.c

@@ -710,12 +710,12 @@ router_set_networkstatus_v2(const char *s, time_t arrived_at,
   if (!found)
     smartlist_add(networkstatus_v2_list, ns);
 
-/*XXXX021 magic. */
-/*DOCDOC */
-#define V2_NETWORKSTATUS_LIFETIME (3*60*60)
+/** Retain any routerinfo mentioned in a V2 networkstatus for at least this
+ * long. */
+#define V2_NETWORKSTATUS_ROUTER_LIFETIME (3*60*60)
 
   {
-    time_t live_until = ns->published_on + V2_NETWORKSTATUS_LIFETIME;
+    time_t live_until = ns->published_on + V2_NETWORKSTATUS_ROUTER_LIFETIME;
     SMARTLIST_FOREACH(ns->entries, routerstatus_t *, rs,
     {
       signed_descriptor_t *sd =
@@ -1755,7 +1755,7 @@ routers_update_status_from_consensus_networkstatus(smartlist_t *routers,
   /* Now update last_listed_as_valid_until from v2 networkstatuses. */
   /* XXXX If this is slow, we need to rethink the code. */
   SMARTLIST_FOREACH(networkstatus_v2_list, networkstatus_v2_t *, ns, {
-    time_t live_until = ns->published_on + V2_NETWORKSTATUS_LIFETIME;
+    time_t live_until = ns->published_on + V2_NETWORKSTATUS_ROUTER_LIFETIME;
     SMARTLIST_FOREACH_JOIN(ns->entries, routerstatus_t *, rs,
                          routers, routerinfo_t *, ri,
                          memcmp(rs->identity_digest,

src/or/rephist.c

@@ -1263,9 +1263,9 @@ bw_array_new(void)
   return b;
 }
 
-/* DOCDOC read_array */
+/** Recent history of bandwidth observations for read operations. */
 static bw_array_t *read_array = NULL;
-/* DOCDOC write_array */
+/** Recent history of bandwidth observations for write operations. */
 static bw_array_t *write_array = NULL;
 
 /** Set up read_array and write_array. */
@@ -1913,7 +1913,7 @@ typedef struct hs_usage_current_observation_period_t {
   time_t start_of_next_period;
 } hs_usage_current_observation_period_t;
 
-/* DOCDOC current_period */
+/** Usage statistics for the current observation period. */
 static hs_usage_current_observation_period_t *current_period = NULL;
 /* DOCDOC publish_total */
 static hs_usage_service_related_observation_t *publish_total = NULL;

src/or/routerlist.c

@@ -80,9 +80,12 @@ static smartlist_t *warned_nicknames = NULL;
  * download is low. */
 static time_t last_routerdesc_download_attempted = 0;
 
-/* DOCDOC This is a massive massive kludge XXXX */
-static uint64_t sl_last_total_weighted_bw = 0;
-static uint64_t sl_last_weighted_bw_of_me = 0;
+/** When we last computed the weights to use for bandwidths on directory
+ * requests, what were the total weighted bandwidth, and our share of that
+ * bandwidth?  Used to determine what fraction of directory requests we should
+ * expect to see. */
+static uint64_t sl_last_total_weighted_bw = 0,
+  sl_last_weighted_bw_of_me = 0;
 
 /** Return the number of directory authorities whose type matches some bit set
  * in <b>type</b>  */
@@ -899,7 +902,10 @@ router_pick_directory_server(authority_type_t type, int flags)
   return choice;
 }
 
-/** DOCDOC */
+/** Try to determine which fraction of v2 and v3 directory requsts aimed at
+ * caches will be sent to us. Set *<b>v2_share_out</b> and
+ * *<b>v3_share_out</b> to the fractions of v2 and v3 protocol shares we
+ * expect to see, respectively.  Return 0 on success, negative on failue. */
 int
 router_get_my_share_of_directory_requests(double *v2_share_out,
                                           double *v3_share_out)
@@ -915,6 +921,7 @@ router_get_my_share_of_directory_requests(double *v2_share_out,
     return -1;
 
   /* Calling for side effect */
+  /* XXXX This is a bit of a kludge */
   if (rs->is_v2_dir) {
     sl_last_total_weighted_bw = 0;
     router_pick_directory_server(V2_AUTHORITY, pds_flags);
@@ -4379,7 +4386,10 @@ get_dir_info_status_string(void)
   return dir_info_status;
 }
 
-/* DOCDOC count_usable_descriptors */
+/** Iterate over the servers listed in <b>consensus</b>, and count how many of
+ * them seem like ones we'd use, and how many of <em>those</em> we have
+ * descriptors for.  Store the former in *<b>num_usable</b> and the latter in
+ * *<b>num_present</b>.  */
 static void
 count_usable_descriptors(int *num_present, int *num_usable,
                          const networkstatus_t *consensus,