[or-cvs] r13405: Fix a bunch of DOCDOC items; document the --quiet flag; refa (in tor/trunk: . doc src/common src/or src/tools)

nickm at seul.org nickm at seul.org
Wed Feb 6 16:58:06 UTC 2008


Author: nickm
Date: 2008-02-06 11:58:05 -0500 (Wed, 06 Feb 2008)
New Revision: 13405

Modified:
   tor/trunk/
   tor/trunk/doc/tor.1.in
   tor/trunk/src/common/log.c
   tor/trunk/src/common/tortls.c
   tor/trunk/src/common/tortls.h
   tor/trunk/src/common/util.c
   tor/trunk/src/or/buffers.c
   tor/trunk/src/or/connection.c
   tor/trunk/src/or/control.c
   tor/trunk/src/or/cpuworker.c
   tor/trunk/src/or/dirserv.c
   tor/trunk/src/or/dirvote.c
   tor/trunk/src/or/main.c
   tor/trunk/src/or/networkstatus.c
   tor/trunk/src/or/or.h
   tor/trunk/src/or/policies.c
   tor/trunk/src/or/rendservice.c
   tor/trunk/src/or/routerlist.c
   tor/trunk/src/tools/tor-gencert.c
Log:
 r17947 at 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.



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r17947] on 8246c3cf-6607-4228-993b-4d95d33730f1

Modified: tor/trunk/doc/tor.1.in
===================================================================
--- tor/trunk/doc/tor.1.in	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/doc/tor.1.in	2008-02-06 16:58:05 UTC (rev 13405)
@@ -49,9 +49,15 @@
 .LP
 .TP
 \fB--version\fP
-Display Tor version.
+Display Tor version and exit.
 .LP
 .TP
+\fB--quiet\fP
+Do not start Tor with a console log unless explicitly requested to do
+so.  (By default, Tor starts out logging messages at level "notice" or
+higher to the console, until it has parsed its configuration.)
+.LP
+.TP
 Other options can be specified either on the command-line (\fI--option
 value\fR), or in the configuration file (\fIoption value\fR or
 \fIoption "value"\fR).  Options are case-insensitive.  C-style escaped

Modified: tor/trunk/src/common/log.c
===================================================================
--- tor/trunk/src/common/log.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/common/log.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -457,8 +457,9 @@
   }
 }
 
-/** Add a log handler to send all messages of severity <b>loglevel</b>
- * or higher to <b>stream</b>. DOCDOC.*/
+/** Add a log handler named <b>name</b> to send all messages of severity
+ * between <b>loglevelMin</b> and <b>loglevelMax</b> (inclusive) to
+ * <b>stream</b>. */
 static void
 add_stream_log_impl(int loglevelMin, int loglevelMax,
                     const char *name, FILE *stream)

Modified: tor/trunk/src/common/tortls.c
===================================================================
--- tor/trunk/src/common/tortls.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/common/tortls.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -1304,38 +1304,3 @@
   return 1;
 }
 
-#if SSL3_RANDOM_SIZE != TOR_TLS_RANDOM_LEN
-#error "The TOR_TLS_RANDOM_LEN macro is defined incorrectly.  That's a bug."
-#endif
-
-/** DOCDOC */
-int
-tor_tls_get_random_values(tor_tls_t *tls, char *client_random_out,
-                          char *server_random_out)
-{
-  tor_assert(tls && tls->ssl);
-  if (!tls->ssl->s3)
-    return -1;
-  memcpy(client_random_out, tls->ssl->s3->client_random, SSL3_RANDOM_SIZE);
-  memcpy(server_random_out, tls->ssl->s3->server_random, SSL3_RANDOM_SIZE);
-  return 0;
-}
-
-/** DOCDOC */
-int
-tor_tls_hmac_with_master_secret(tor_tls_t *tls, char *hmac_out,
-                                const char *data, size_t data_len)
-{
-  SSL_SESSION *s;
-  tor_assert(tls && tls->ssl);
-  if (!(s = SSL_get_session(tls->ssl)))
-    return -1;
-  if (s->master_key_length < 0)
-    return -1;
-  crypto_hmac_sha1(hmac_out,
-                   (const char*)s->master_key,
-                   (size_t)s->master_key_length,
-                   data, data_len);
-  return 0;
-}
-

Modified: tor/trunk/src/common/tortls.h
===================================================================
--- tor/trunk/src/common/tortls.h	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/common/tortls.h	2008-02-06 16:58:05 UTC (rev 13405)
@@ -43,9 +43,6 @@
   case TOR_TLS_ERROR_NO_ROUTE:                  \
   case TOR_TLS_ERROR_TIMEOUT
 
-/**DOCDOC*/
-#define TOR_TLS_RANDOM_LEN 32
-
 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
 const char *tor_tls_err_to_string(int err);
 
@@ -79,10 +76,6 @@
                              size_t *n_read, size_t *n_written);
 
 int tor_tls_used_v1_handshake(tor_tls_t *tls);
-int tor_tls_get_random_values(tor_tls_t *tls, char *client_random_out,
-                              char *server_random_out);
-int tor_tls_hmac_with_master_secret(tor_tls_t *tls, char *hmac_out,
-                                    const char *data, size_t data_len);
 
 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
  */

Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/common/util.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -1298,7 +1298,10 @@
   return 0;
 }
 
-/** DOCDOC */
+/** Given an <b>interval</b> in seconds, try to write it to the
+ * <b>out_len</b>-byte buffer in <b>out</b> in a human-readable form.
+ * Return 0 on success, -1 on failure.
+ */
 int
 format_time_interval(char *out, size_t out_len, long interval)
 {
@@ -1932,13 +1935,19 @@
 
 #define TOR_ISODIGIT(c) ('0' <= (c) && (c) <= '7')
 
-/* DOCDOC */
+/* Given a c-style double-quoted escaped string in <b>s</b>, extract and
+ * decode its contents into a newly allocated string.  On success, assign this
+ * string to *<b>result</b>, assign its length to <b>size_out</b> (if
+ * provided), and return a pointer to the position in <b>s</b> immediately
+ * after the string.  On failure, return NULL.
+ */
 static const char *
 unescape_string(const char *s, char **result, size_t *size_out)
 {
   const char *cp;
   char *out;
-  tor_assert(s[0] == '\"');
+  if (s[0] != '\"')
+    return NULL;
   cp = s+1;
   while (1) {
     switch (*cp) {

Modified: tor/trunk/src/or/buffers.c
===================================================================
--- tor/trunk/src/or/buffers.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/buffers.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -580,6 +580,7 @@
   }
 }
 
+/** 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 @@
   }
 }
 
+/** 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 @@
   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)
 {

Modified: tor/trunk/src/or/connection.c
===================================================================
--- tor/trunk/src/or/connection.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/connection.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -1650,7 +1650,10 @@
   }
 }
 
-/** 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)

Modified: tor/trunk/src/or/control.c
===================================================================
--- tor/trunk/src/or/control.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/control.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -364,42 +364,55 @@
   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 @@
  * 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 @@
     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));

Modified: tor/trunk/src/or/cpuworker.c
===================================================================
--- tor/trunk/src/or/cpuworker.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/cpuworker.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -431,10 +431,13 @@
   });
 }
 
-/** 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,

Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/dirserv.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -2283,16 +2283,6 @@
 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,

Modified: tor/trunk/src/or/dirvote.c
===================================================================
--- tor/trunk/src/or/dirvote.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/dirvote.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -36,17 +36,6 @@
 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 @@
   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 @@
   return result;
 }
 
-/**DOCDOC*/
+/** Return true iff <b>method</b> is a consensus method that we support. */
 static int
 consensus_method_is_supported(int method)
 {

Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/main.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -1785,7 +1785,7 @@
   /* 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) {

Modified: tor/trunk/src/or/networkstatus.c
===================================================================
--- tor/trunk/src/or/networkstatus.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/networkstatus.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -1206,6 +1206,7 @@
 /* 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 @@
 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);
 }

Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/or.h	2008-02-06 16:58:05 UTC (rev 13405)
@@ -3058,6 +3058,16 @@
 /** 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);

Modified: tor/trunk/src/or/policies.c
===================================================================
--- tor/trunk/src/or/policies.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/policies.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -744,7 +744,7 @@
   return 0;
 }
 
-/** DOCDOC */
+/** Replace the exit policy of <b>r</b> with reject *:*. */
 void
 policies_set_router_exitpolicy_to_reject_all(routerinfo_t *r)
 {

Modified: tor/trunk/src/or/rendservice.c
===================================================================
--- tor/trunk/src/or/rendservice.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/rendservice.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -48,6 +48,7 @@
   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 @@
   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;

Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/or/routerlist.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -55,7 +55,8 @@
  * 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 @@
 
 #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 @@
   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 @@
   } 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)
 {

Modified: tor/trunk/src/tools/tor-gencert.c
===================================================================
--- tor/trunk/src/tools/tor-gencert.c	2008-02-06 14:09:19 UTC (rev 13404)
+++ tor/trunk/src/tools/tor-gencert.c	2008-02-06 16:58:05 UTC (rev 13405)
@@ -36,6 +36,7 @@
 #define SIGNING_KEY_BITS 1024
 #define DEFAULT_LIFETIME 12
 
+/* These globals are set via command line options. */
 char *identity_key_file = NULL;
 char *signing_key_file = NULL;
 char *certificate_file = NULL;
@@ -48,7 +49,7 @@
 EVP_PKEY *identity_key = NULL;
 EVP_PKEY *signing_key = NULL;
 
-/* DOCDOC */
+/** Write a usage message for tor-gencert to stderr. */
 static void
 show_help(void)
 {
@@ -82,7 +83,9 @@
   }
 }
 
-/** DOCDOC */
+/** Read the command line options from <b>argc</b> and <b>argv</b>,
+ * setting global option vars as needed.
+ */
 static int
 parse_commandline(int argc, char **argv)
 {
@@ -170,7 +173,10 @@
   return 0;
 }
 
-/** DOCDOC */
+/** Try to read the identity key from <b>identity_key_file</b>.  If no such
+ * file exists and create_identity_key is set, make a new identity key and
+ * store it.  Return 0 on success, nonzero on failure.
+ */
 static int
 load_identity_key(void)
 {
@@ -240,7 +246,8 @@
   return 0;
 }
 
-/** DOCDOC */
+/** Load a saved signing key from disk.  Return 0 on success, nonzero on
+ * failure. */
 static int
 load_signing_key(void)
 {
@@ -258,7 +265,8 @@
   return 0;
 }
 
-/** DOCDOC */
+/** Generate a new signing key and write it to disk.  Return 0 on success,
+ * nonzero on failure. */
 static int
 generate_signing_key(void)
 {
@@ -295,6 +303,8 @@
   return 0;
 }
 
+/** Encode <b>key</b> in the format used in directory documents; return
+ * a newly allocated string holding the result or NULL on failure. */
 static char *
 key_to_string(EVP_PKEY *key)
 {
@@ -322,6 +332,7 @@
   return result;
 }
 
+/** Set <b>out</b> to the hex-encoded fingerprint of <b>pkey</b>. */
 static int
 get_fingerprint(EVP_PKEY *pkey, char *out)
 {
@@ -334,6 +345,8 @@
   return r;
 }
 
+/** Generate a new certificate for our loaded or generated keys, and write it
+ * to disk.  Return 0 on success, nonzero on failure. */
 static int
 generate_certificate(void)
 {



More information about the tor-commits mailing list