r12123@Kushana: nickm | 2007-02-02 13:57:42 -0500

 Resolve remaining DOCDOC comments.


svn:r9476

5 files changed, 77 insertions, 38 deletions

diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c
index 61dca3fbf..2f01f75fd 100644
--- a/src/or/circuitlist.c
+++ b/src/or/circuitlist.c
@@ -634,12 +634,10 @@ circuit_get_by_rend_query_and_purpose(const char *rend_query, uint8_t purpose)
   return NULL;
 }
 
-/** Return the first circuit in global_circuitlist after <b>start</b>
- * whose purpose is <b>purpose</b> is purpose, and (if set) whose
- * <b>digest</b> matches the rend_pk_digest field. Return NULL if no
- * circuit is found.
- * If <b>start</b> is NULL, begin at the start of the list.
- * DOCDOC origin.
+/** Return the first circuit originating here in global_circuitlist after
+ * <b>start</b> whose purpose is <b>purpose</b> is purpose, and where
+ * <b>digest</b> (if set) matches the rend_pk_digest field. Return NULL if no
+ * circuit is found.  If <b>start</b> is NULL, begin at the start of the list.
  */
 origin_circuit_t *
 circuit_get_next_by_pk_and_purpose(origin_circuit_t *start,
@@ -666,7 +664,9 @@ circuit_get_next_by_pk_and_purpose(origin_circuit_t *start,
   return NULL;
 }
 
-/* DOCDOC */
+/** Return the first OR circuit in the global list whose purpose is
+ * <b>purpose</b>, and whose rend_token is the <b>len</b>-byte
+ * <b>token</b>.  */
 static or_circuit_t *
 circuit_get_by_rend_token_and_purpose(uint8_t purpose, const char *token,
                                       size_t len)
diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c
index f82b1bab2..0afe3013c 100644
--- a/src/or/connection_edge.c
+++ b/src/or/connection_edge.c
@@ -632,7 +632,8 @@ addressmap_virtaddress_remove(const char *address, addressmap_entry_t *ent)
   }
 }
 
-/* DOCDOC */
+/** Remove <b>ent</b> (which must be mapped to by <b>address</b>) from the
+ * client address maps. */
 static void
 addressmap_ent_remove(const char *address, addressmap_entry_t *ent)
 {
@@ -708,7 +709,9 @@ addressmap_rewrite(char *address, size_t maxlen)
   /* it's fine to rewrite a rewrite, but don't loop forever */
 }
 
-/* DOCDOC */
+/** If we have a cached reverse DNS entry for the address stored in the
+ * <b>maxlen</b>-byte buffer <b>address</b> (typically, a dotted quad) with
+ * the cached value and return 1.  Otherwise return  0. */
 static int
 addressmap_rewrite_reverse(char *address, size_t maxlen)
 {
@@ -898,7 +901,15 @@ client_dns_set_addressmap(const char *address, uint32_t val,
   client_dns_set_addressmap_impl(address, valbuf, exitname, ttl);
 }
 
-/** DOCDOC */
+/** Add a cache entry noting that <b>address</b> (ordinarily a dotted quad)
+ * resolved via a RESOLVE_PTR request to the hostname <b>v</b>.
+ *
+ * If <b>exitname</b> is defined, then append the addresses with
+ * ".exitname.exit" before registering the mapping.
+ *
+ * If <b>ttl</b> is nonnegative, the mapping will be valid for
+ * <b>ttl</b>seconds; otherwise, we use the default.
+ */
 static void
 client_dns_set_reverse_addressmap(const char *address, const char *v,
                                   const char *exitname,
@@ -2003,11 +2014,10 @@ connection_ap_handshake_socks_resolved(edge_connection_t *conn,
  * socks version, etc, and mark <b>conn</b> as completed with SOCKS
  * handshaking.
  *
- * If <b>reply</b> is defined, then write <b>replylen</b> bytes of it
- * to conn and return, else reply based on <b>status</b>.
- *
- * If <b>reply</b> is undefined, <b>status</b> can't be 0.
- * DOCDOC endreason
+ * If <b>reply</b> is defined, then write <b>replylen</b> bytes of it to conn
+ * and return, else reply based on <b>endreason</b> (one of
+ * END_STREAM_REASON_*). If <b>reply</b> is undefined, <b>endreason</b> can't 0
+ * or REASON_DONE.  Send endreason to the controller, if appropriate.
  */
 void
 connection_ap_handshake_socks_reply(edge_connection_t *conn, char *reply,
diff --git a/src/or/control.c b/src/or/control.c
index be404bfdd..0b34b0d8a 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -631,7 +631,13 @@ send_control0_event(uint16_t event, uint32_t len, const char *body)
 /* Send an event to all v1 controllers that are listening for code
  * <b>event</b>.  The event's body is given by <b>msg</b>.
  *
- * docdoc which, is_extended */
+ * If <b>which</b> & SHORT_NAMES, the event contains short-format names: send
+ * it to controllers that haven't enabled the VERBOSE_NAMES feature.  If
+ * <b>which</b> & LONG_NAMES, the event contains long-format names: sent it
+ * to contollers that <em>have</em> enabled VERBOSE_NAMES.
+ *
+ * The EXTENDED_FORMAT and NONEXTENDED_FORMAT flags behaves similarly with
+ * respect to the EXTENDED_EVENTS feature. */
 static void
 send_control1_event_string(uint16_t event, event_format_t which,
                            const char *msg)
@@ -3118,7 +3124,8 @@ write_stream_target_to_buf(edge_connection_t *conn, char *buf, size_t len)
   return 0;
 }
 
-/* DOCDOC */
+/** Convert the reason for ending a stream <b>reason</b> into the format used
+ * in STREAM events. Return NULL if the reason is unrecognized.*/
 static const char *
 stream_end_reason_to_string(int reason)
 {
@@ -3585,7 +3592,8 @@ control_event_or_authdir_new_descriptor(const char *action,
   return 0;
 }
 
-/* DOCDOC takes a list of local_routerstatus_t */
+/** Called when the local_routerstatus_ts <b>statuses</b> have changed: sends
+ * an NS event to any controller that cares. */
 int
 control_event_networkstatus_changed(smartlist_t *statuses)
 {
@@ -3612,7 +3620,8 @@ control_event_networkstatus_changed(smartlist_t *statuses)
   return 0;
 }
 
-/* DOCDOC */
+/** Called when a single local_routerstatus_t has changed: Sends an NS event
+ * to any countroller that cares. */
 int
 control_event_networkstatus_changed_single(local_routerstatus_t *rs)
 {
@@ -3638,7 +3647,10 @@ control_event_my_descriptor_changed(void)
   return 0;
 }
 
-/* DOCDOC */
+/** Helper: sents a status event where <b>type</b> is one of
+ * EVENT_STATUS_{GENERAL,CLIENT,SERVER}, where <b>severity</b> is one of
+ * LOG_{NOTICE,WARN,ERR}, and where <b>format</b> is a print-style format
+ * string corresponding to <b>args</b>. */
 static int
 control_event_status(int type, int severity, const char *format, va_list args)
 {
@@ -3683,7 +3695,8 @@ control_event_status(int type, int severity, const char *format, va_list args)
   return 0;
 }
 
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_GENERAL event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
 int
 control_event_general_status(int severity, const char *format, ...)
 {
@@ -3698,7 +3711,8 @@ control_event_general_status(int severity, const char *format, ...)
   return r;
 }
 
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_CLIENT event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
 int
 control_event_client_status(int severity, const char *format, ...)
 {
@@ -3713,7 +3727,8 @@ control_event_client_status(int severity, const char *format, ...)
   return r;
 }
 
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_SERVER event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
 int
 control_event_server_status(int severity, const char *format, ...)
 {
@@ -3728,7 +3743,9 @@ control_event_server_status(int severity, const char *format, ...)
   return r;
 }
 
-/** DOCDOC */
+/** Called when the status of an entry guard with the given <b>nickname</b>
+ * and identity <b>digest</b> has changed to <b>status</b>: tells any
+ * controllers that care.  */
 int
 control_event_guard(const char *nickname, const char *digest,
                     const char *status)
diff --git a/src/or/directory.c b/src/or/directory.c
index 87977a9c0..3db8d938d 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -1444,10 +1444,13 @@ already_fetching_directory(int purpose)
 #undef INSTRUMENT_DOWNLOADS
 
 #ifdef INSTRUMENT_DOWNLOADS
-/** DOCDOC */
+/** 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. */
 static strmap_t *request_bytes_map = NULL;
 
-/** DOCDOC */
+/** Called when we just transmitted or received <b>bytes</b> worth of data
+ * because of a request of type <b>key</b> (an arbitrary identifier): adds
+ * <b>bytes</b> to the total associated with key. */
 static void
 note_request(const char *key, size_t bytes)
 {
@@ -1463,7 +1466,8 @@ note_request(const char *key, size_t bytes)
   *n += bytes;
 }
 
-/** DOCDOC */
+/** Return a newly allocated string holding a summary of bytes used per
+ * request type. */
 char *
 directory_dump_request_log(void)
 {
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 132e8339b..3060375e4 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -906,6 +906,7 @@ router_find_exact_exit_enclave(const char *address, uint16_t port)
  * If <b>need_uptime</b> is non-zero, we require a minimum uptime.
  * If <b>need_capacity</b> is non-zero, we require a minimum advertised
  * bandwidth.
+ * If <b>need_guard</b>, we require that the router is a possible entry guard.
  */
 int
 router_is_unreliable(routerinfo_t *router, int need_uptime,
@@ -939,7 +940,10 @@ router_get_advertised_bandwidth(routerinfo_t *router)
  * If <b>statuses</b> is zero, then <b>sl</b> is a list of
  * routerinfo_t's. Otherwise it's a list of routerstatus_t's.
  *
- * DOCDOC for_exit
+ * If <b>for_exit</b>, we're picking an exit node: consider all nodes'
+ * bandwidth equally regardless of their Exit status.  If not <b>for_exit</b>,
+ * we're picking a non-exit node: weight exit-node's bandwidth downwards
+ * depending on the smallness of the fraction of Exit-to-total bandwidth.
  */
 static void *
 smartlist_choose_by_bandwidth(smartlist_t *sl, int for_exit, int statuses)
@@ -972,6 +976,9 @@ smartlist_choose_by_bandwidth(smartlist_t *sl, int for_exit, int statuses)
           this_bw = status->is_fast ? 40000 : 20000;
         else /* assume it'll be the average we've seen so far */
           this_bw = (uint32_t)(partial/i);
+        /*XXXX012 The above calculation is an awful hack, and makes our
+         * algorithm hard to describe sanely. Could we do better with a second
+         * pass through the list? -NM */
       }
     } else {
       router = smartlist_get(sl, i);
@@ -1063,8 +1070,11 @@ routerstatus_sl_choose_by_bandwidth(smartlist_t *sl)
  * a minimum uptime, return one of those.
  * If <b>need_capacity</b> is non-zero, weight your choice by the
  * advertised capacity of each router.
- *
- * DOCDOC allow_invalid, need_guard, weight_for_exit
+ * If ! <b>allow_invalid</b>, consider only Valid routers.
+ * If <b>need_guard</b>, consider only Guard routers.
+ * If <b>weight_for_exit</b>, we weight bandwidths as if picking an exit node,
+ * otherwise we weight bandwidths for picking a relay node (that is, possibly
+ * discounting exit nodes).
  */
 routerinfo_t *
 router_choose_random_node(const char *preferred,
@@ -3782,15 +3792,13 @@ router_list_client_downloadable(void)
 /** Initiate new router downloads as needed, using the strategy for
  * non-directory-servers.
  *
- * We only allow one router descriptor download at a time.
- * If we have less than two network-status documents, we ask
- * a directory for "all descriptors."
- * Otherwise, we ask for all descriptors that we think are different
- * from what we have.
+ * We don't launch any downloads if there are fewer than MAX_DL_TO_DELAY
+ * descriptors to get and less than MAX_CLIENT_INTERVAL_WITHOUT_REQUEST
+ * seconds have passed.
  *
- * DOCDOC The above comment doesn't match the behavior of the function.
- * I guess one of them is wrong, and I guess it's the comment. -RD
- */
+ * Otherwise, we ask for all descriptors that we think are different from what
+ * we have, and that we don't currently have an in-progress download attempt
+ * for. */
 static void
 update_router_descriptor_client_downloads(time_t now)
 {