r17947@catbus: nickm | 2008-02-06 11:57:53 -0500

 Fix a bunch of DOCDOC items; document the --quiet flag; refactor a couple of XXXX020 items.


svn:r13405

12 files changed, 88 insertions, 84 deletions

diff --git a/src/or/buffers.c b/src/or/buffers.c
index 86a82e1779..940c6ccb46 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -580,6 +580,7 @@ read_to_chunk(buf_t *buf, chunk_t *chunk, int fd, size_t at_most,
   }
 }
 
+/** DOCDOC */
 static INLINE int
 read_to_chunk_tls(buf_t *buf, chunk_t *chunk, tor_tls_t *tls,
                   size_t at_most)
@@ -722,6 +723,7 @@ flush_chunk(int s, buf_t *buf, chunk_t *chunk, size_t sz,
   }
 }
 
+/** DOCDOC */
 static INLINE int
 flush_chunk_tls(tor_tls_t *tls, buf_t *buf, chunk_t *chunk,
                 size_t sz, size_t *buf_flushlen)
@@ -1518,7 +1520,8 @@ peek_buf_has_control0_command(buf_t *buf)
   return 0;
 }
 
-/** DOCDOC */
+/** Return the index within <b>buf</b> at which <b>ch</b> first appears,
+ * or -1 if <b>ch</b> does not appear on buf. */
 static int
 buf_find_offset_of_char(buf_t *buf, char ch)
 {
diff --git a/src/or/connection.c b/src/or/connection.c
index 845f0ff83d..484140f4cb 100644
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -1650,7 +1650,10 @@ connection_bucket_init(void)
   }
 }
 
-/** DOCDOC */
+/** Refill a single <b>bucket</b> called <b>name</b> with bandwith rate
+ * <b>rate</b> and bandwidth burst <b>burst</b>, assuming that
+ * <b>seconds_elapsed</b> seconds have passed since the last call.
+ **/
 static void
 connection_bucket_refill_helper(int *bucket, int rate, int burst,
                                 int seconds_elapsed, const char *name)
diff --git a/src/or/control.c b/src/or/control.c
index ff3a4b10ae..4a44f0c071 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -364,42 +364,55 @@ read_escaped_data(const char *data, size_t len, char **out)
   return outp - *out;
 }
 
-/** DOCDOC */
-static const char *
-extract_escaped_string(const char *start, size_t in_len_max,
-                       char **out, size_t *out_len)
+/** If the first <b>in_len_max</b> characters in <b>start<b> contain a
+ * double-quoted string with escaped characters, return the length of that
+ * string (as encoded, including quotes).  Otherwise return -1. */
+static INLINE int
+get_escaped_string_length(const char *start, size_t in_len_max,
+                          int *chars_out)
 {
   const char *cp, *end;
-  size_t len=0;
+  int chars = 0;
 
   if (*start != '\"')
-    return NULL;
+    return -1;
 
   cp = start+1;
   end = start+in_len_max;
 
   /* Calculate length. */
   while (1) {
-    if (cp >= end)
-      return NULL;
-    else if (*cp == '\\') {
+    if (cp >= end) {
+      return -1; /* Too long. */
+    } else if (*cp == '\\') {
       if (++cp == end)
-        return NULL; /* Can't escape EOS. */
+        return -1; /* Can't escape EOS. */
       ++cp;
-      ++len;
+      ++chars;
     } else if (*cp == '\"') {
       break;
     } else {
       ++cp;
-      ++len;
+      ++chars;
     }
   }
-  end = cp;
+  if (chars_out)
+    *chars_out = chars;
+  return cp - start+1;
+}
 
-  *out_len = end-start+1;
+/** As decode_escaped_string, but does not decode the string: copies the
+ * entire thing, including quotation marks. */
+static const char *
+extract_escaped_string(const char *start, size_t in_len_max,
+                       char **out, size_t *out_len)
+{
+  int length = get_escaped_string_length(start, in_len_max, NULL);
+  if (length<0)
+    return NULL;
+  *out_len = length;
   *out = tor_strndup(start, *out_len);
-
-  return end+1;
+  return start+length;
 }
 
 /** Given a pointer to a string starting at <b>start</b> containing
@@ -410,40 +423,22 @@ extract_escaped_string(const char *start, size_t in_len_max,
  * store its length in <b>out_len</b>.  On success, return a pointer to the
  * character immediately following the escaped string.  On failure, return
  * NULL. */
-/* XXXX020 fold into extract_escaped_string */
 static const char *
-get_escaped_string(const char *start, size_t in_len_max,
+decode_escaped_string(const char *start, size_t in_len_max,
                    char **out, size_t *out_len)
 {
   const char *cp, *end;
   char *outp;
-  size_t len=0;
+  int len, n_chars = 0;
 
-  if (*start != '\"')
+  len = get_escaped_string_length(start, in_len_max, &n_chars);
+  if (len<0)
     return NULL;
 
-  cp = start+1;
-  end = start+in_len_max;
-
-  /* Calculate length. */
-  while (1) {
-    if (cp >= end)
-      return NULL;
-    else if (*cp == '\\') {
-      if (++cp == end)
-        return NULL; /* Can't escape EOS. */
-      ++cp;
-      ++len;
-    } else if (*cp == '\"') {
-      break;
-    } else {
-      ++cp;
-      ++len;
-    }
-  }
-  end = cp;
+  end = start+len-1; /* Index of last quote. */
+  tor_assert(*end == '\"');
   outp = *out = tor_malloc(len+1);
-  *out_len = len;
+  *out_len = n_chars;
 
   cp = start+1;
   while (cp < end) {
@@ -1030,7 +1025,7 @@ handle_control_authenticate(control_connection_t *conn, uint32_t len,
     password = tor_strdup("");
     password_len = 0;
   } else {
-    if (!get_escaped_string(body, len, &password, &password_len)) {
+    if (!decode_escaped_string(body, len, &password, &password_len)) {
       connection_write_str_to_buf("551 Invalid quoted string.  You need "
             "to put the password in double quotes.\r\n", conn);
       connection_mark_for_close(TO_CONN(conn));
diff --git a/src/or/cpuworker.c b/src/or/cpuworker.c
index 7d5cf679b5..ff07f21b9f 100644
--- a/src/or/cpuworker.c
+++ b/src/or/cpuworker.c
@@ -431,10 +431,13 @@ cull_wedged_cpuworkers(void)
   });
 }
 
-/** If cpuworker is defined, assert that he's idle, and use him. Else,
- * look for an idle cpuworker and use him. If none idle, queue task onto
- * the pending onion list and return.
- * DOCDOC this function is now less general
+/** Try to tell a cpuworker to perform the public key operations necessary to
+ * respond to <b>onionskin</b> for the circuit <b>circ</b>.
+ *
+ * If <b>cpuworker</b> is defined, assert that he's idle, and use him. Else,
+ * look for an idle cpuworker and use him. If none idle, queue task onto the
+ * pending onion list and return.  Return 0 if we successfully assign the
+ * task, or -1 on failure.
  */
 int
 assign_onionskin_to_cpuworker(connection_t *cpuworker,
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 4e495c286a..b36bfa067b 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -2283,16 +2283,6 @@ dirserv_generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
 static cached_dir_t *
 generate_v2_networkstatus_opinion(void)
 {
-/** Amount of space to allocate for each entry. (r line and s line.) */
-#define RS_ENTRY_LEN                                                    \
-  ( /* first line */                                                    \
-   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
-   5*2 /* ports */ + 10 /* punctuation */ +                             \
-   /* second line */                                                    \
-   (MAX_FLAG_LINE_LEN) +                                                \
-   /* third line */                                                     \
-   (MAX_V_LINE_LEN))
-
   cached_dir_t *r = NULL;
   size_t len, identity_pkey_len;
   char *status = NULL, *client_versions = NULL, *server_versions = NULL,
diff --git a/src/or/dirvote.c b/src/or/dirvote.c
index fbbdec9743..1a8ea052ed 100644
--- a/src/or/dirvote.c
+++ b/src/or/dirvote.c
@@ -36,17 +36,6 @@ char *
 format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
                           networkstatus_t *v3_ns)
 {
-/** Amount of space to allocate for each entry: r, s, and v lines. */
-#define RS_ENTRY_LEN                                                    \
-  ( /* first line */                                                    \
-   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
-   5*2 /* ports */ + 10 /* punctuation */ +                             \
-   /* second line */                                                    \
-   MAX_FLAG_LINE_LEN +                                                  \
-   /* v line. */                                                        \
-   MAX_V_LINE_LEN                                                       \
-   )
-
   size_t len;
   char *status = NULL;
   const char *client_versions = NULL, *server_versions = NULL;
@@ -367,22 +356,28 @@ hash_list_members(char *digest_out, smartlist_t *lst)
   crypto_free_digest_env(d);
 }
 
-/**DOCDOC*/
+/** Sorting helper: compare two strings based on their values as base-ten
+ * positive integers. (Non-integers are treated as prior to all integers, and
+ * compared lexically.) */
 static int
 _cmp_int_strings(const void **_a, const void **_b)
 {
   const char *a = *_a, *b = *_b;
   int ai = (int)tor_parse_long(a, 10, 1, INT_MAX, NULL, NULL);
   int bi = (int)tor_parse_long(b, 10, 1, INT_MAX, NULL, NULL);
-  if (ai<bi)
+  if (ai<bi) {
     return -1;
-  else if (ai==bi)
+  } else if (ai==bi) {
+    if (ai == 0) /* Parsing failed. */
+      return strcmp(a, b);
     return 0;
-  else
+  } else {
     return 1;
+  }
 }
 
-/**DOCDOC*/
+/** Given a list of networkstatus_t votes, determine and return the number of
+ * the highest consensus method that is supported by 2/3 of the voters. */
 static int
 compute_consensus_method(smartlist_t *votes)
 {
@@ -417,7 +412,7 @@ compute_consensus_method(smartlist_t *votes)
   return result;
 }
 
-/**DOCDOC*/
+/** Return true iff <b>method</b> is a consensus method that we support. */
 static int
 consensus_method_is_supported(int method)
 {
diff --git a/src/or/main.c b/src/or/main.c
index 1628762249..c2ecab64b9 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -1785,7 +1785,7 @@ tor_init(int argc, char *argv[])
   /* We search for the "quiet" option first, since it decides whether we
    * will log anything at all to the command line. */
   for (i=1;i<argc;++i) {
-    if (!strcmp(argv[i], "--quiet")) /*DOCDOC in mangpage.*/
+    if (!strcmp(argv[i], "--quiet"))
       quiet = 1;
   }
   if (!quiet) {
diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c
index d1069940ca..864258583c 100644
--- a/src/or/networkstatus.c
+++ b/src/or/networkstatus.c
@@ -1206,6 +1206,7 @@ networkstatus_get_live_consensus(time_t now)
 /* XXXX020 remove this in favor of get_live_consensus. But actually,
  * leave something like it for bridge users, who need to not totally
  * lose if they spend a while fetching a new consensus. */
+/** DOCDOC */
 networkstatus_t *
 networkstatus_get_reasonably_live_consensus(time_t now)
 {
@@ -1781,8 +1782,7 @@ signed_descs_update_status_from_consensus_networkstatus(smartlist_t *descs)
 char *
 networkstatus_getinfo_helper_single(routerstatus_t *rs)
 {
-  char buf[256];
-  /* XXX020 that 256 above sounds a lot like RS_ENTRY_LEN in dirvote.c */
+  char buf[RS_ENTRY_LEN+1];
   routerstatus_format_entry(buf, sizeof(buf), rs, NULL, 0);
   return tor_strdup(buf);
 }
diff --git a/src/or/or.h b/src/or/or.h
index c2c4c0c560..16a5bceda0 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -3058,6 +3058,16 @@ download_status_is_ready(download_status_t *dls, time_t now,
 /** Length of "r Authority BadDirectory BadExit Exit Fast Guard HSDir Named
  * Running Stable Unnamed V2Dir Valid\n". */
 #define MAX_FLAG_LINE_LEN 96
+/** Amount of space to allocate for each entry: r, s, and v lines. */
+#define RS_ENTRY_LEN                                                    \
+  ( /* first line */                                                    \
+   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
+   5*2 /* ports */ + 10 /* punctuation */ +                             \
+   /* second line */                                                    \
+   MAX_FLAG_LINE_LEN +                                                  \
+   /* v line. */                                                        \
+   MAX_V_LINE_LEN                                                       \
+   )
 #define UNNAMED_ROUTER_NICKNAME "Unnamed"
 
 int connection_dirserv_flushed_some(dir_connection_t *conn);
diff --git a/src/or/policies.c b/src/or/policies.c
index 3b7822fdab..75b07aa623 100644
--- a/src/or/policies.c
+++ b/src/or/policies.c
@@ -744,7 +744,7 @@ policies_parse_exit_policy(config_line_t *cfg, smartlist_t **dest,
   return 0;
 }
 
-/** DOCDOC */
+/** Replace the exit policy of <b>r</b> with reject *:*. */
 void
 policies_set_router_exitpolicy_to_reject_all(routerinfo_t *r)
 {
diff --git a/src/or/rendservice.c b/src/or/rendservice.c
index 46a5e46cec..a1e0ce7950 100644
--- a/src/or/rendservice.c
+++ b/src/or/rendservice.c
@@ -48,6 +48,7 @@ typedef struct rend_service_t {
   char *intro_prefer_nodes; /**< comma-separated list of nicknames */
   char *intro_exclude_nodes; /**< comma-separated list of nicknames */
   /* Other fields */
+  /* DOCDOC All of these fields */
   crypto_pk_env_t *private_key;
   char service_id[REND_SERVICE_ID_LEN_BASE32+1];
   char pk_digest[DIGEST_LEN];
@@ -56,7 +57,6 @@ typedef struct rend_service_t {
   time_t intro_period_started;
   int n_intro_circuits_launched; /**< count of intro circuits we have
                                   * established in this period. */
-  /* DOCDOC undocumented versions */
   rend_service_descriptor_t *desc;
   time_t desc_is_dirty;
   time_t next_upload_time;
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 5219eb7ebd..91936f9e48 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -55,7 +55,8 @@ DECLARE_TYPED_DIGESTMAP_FNS(eimap_, digest_ei_map_t, extrainfo_t)
  * server. */
 static smartlist_t *trusted_dir_servers = NULL;
 
-/** DOCDOC */
+/** List of for a given authority, and download status for latest certificate.
+ */
 typedef struct cert_list_t {
   download_status_t dl_status;
   smartlist_t *certs;
@@ -95,7 +96,8 @@ get_n_authorities(authority_type_t type)
 
 #define get_n_v2_authorities() get_n_authorities(V2_AUTHORITY)
 
-/** DOCDOC */
+/** Helper: Return the cert_list_t for an authority whose authority ID is
+ * <b>id_digest</b>, allocating a new list if necessary. */
 static cert_list_t *
 get_cert_list(const char *id_digest)
 {
@@ -328,10 +330,11 @@ authority_cert_get_by_digests(const char *id_digest,
   return NULL;
 }
 
-/** DOCDOC */
+/** Add every known authority_cert_t to <b>certs_out</b>. */
 void
 authority_cert_get_all(smartlist_t *certs_out)
 {
+  tor_assert(certs_out);
   if (!trusted_dir_certs)
     return;
 
@@ -341,7 +344,9 @@ authority_cert_get_all(smartlist_t *certs_out)
   } DIGESTMAP_FOREACH_END;
 }
 
-/** DOCDOC */
+/** Called when an attempt to download a certificate with the authority with
+ * ID <b>id_digest</b> fails with HTTP response code <b>status</b>: remember
+ * the failure, so we don't try again immediately. */
 void
 authority_cert_dl_failed(const char *id_digest, int status)
 {