Resolve all currently pending DOCDOC items in master

12 files changed, 95 insertions, 43 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 093106120d..49a4afe733 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -143,7 +143,8 @@ tor_open_cloexec(const char *path, int flags, unsigned mode)
   return fd;
 }
 
-/** DOCDOC */
+/** As fpoen(path,mode), but ensures that the O_CLOEXEC bit is set on the
+ * underlying file handle. */
 FILE *
 tor_fopen_cloexec(const char *path, const char *mode)
 {
diff --git a/src/common/util.c b/src/common/util.c
index e7979d85b5..b3145aefe3 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -3323,7 +3323,15 @@ process_handle_new(void)
   return out;
 }
 
-/*DOCDOC*/
+/**
+ * @name child-process states
+ *
+ * Each of these values represents a possible state that a child process can
+ * be in.  They're used to determine what to say when telling the parent how
+ * far along we were before failure.
+ *
+ * @{
+ */
 #define CHILD_STATE_INIT 0
 #define CHILD_STATE_PIPE 1
 #define CHILD_STATE_MAXFD 2
@@ -3334,7 +3342,7 @@ process_handle_new(void)
 #define CHILD_STATE_CLOSEFD 7
 #define CHILD_STATE_EXEC 8
 #define CHILD_STATE_FAILEXEC 9
-
+/** @} */
 /** Start a program in the background. If <b>filename</b> contains a '/', then
  * it will be treated as an absolute or relative path.  Otherwise, on
  * non-Windows systems, the system path will be searched for <b>filename</b>.
diff --git a/src/common/util.h b/src/common/util.h
index 36601fa790..ae40898de7 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -409,8 +409,10 @@ void set_environment_variable_in_smartlist(struct smartlist_t *env_vars,
 #define PROCESS_STATUS_ERROR -1
 
 #ifdef UTIL_PRIVATE
-/*DOCDOC*/
+/** Structure to represent the state of a process with which Tor is
+ * communicating. The contents of this structure are private to util.c */
 struct process_handle_t {
+  /** One of the PROCESS_STATUS_* values */
   int status;
 #ifdef _WIN32
   HANDLE stdout_pipe;
diff --git a/src/or/config.c b/src/or/config.c
index 8a19ed6d44..5f5960f945 100644
--- a/src/or/config.c
+++ b/src/or/config.c
@@ -675,11 +675,12 @@ static const config_format_t state_format = {
 
 /** Command-line and config-file options. */
 static or_options_t *global_options = NULL;
-/** DOCDOC */
+/** The fallback options_t object; this is where we look for options not
+ * in torrc before we fall back to Tor's defaults. */
 static or_options_t *global_default_options = NULL;
 /** Name of most recently read torrc file. */
 static char *torrc_fname = NULL;
-/** DOCDOC */
+/** Name of the most recently read torrc-defaults file.*/
 static char *torrc_defaults_fname;
 /** Persistent serialized state. */
 static or_state_t *global_state = NULL;
@@ -4345,8 +4346,8 @@ get_windows_conf_root(void)
 }
 #endif
 
-/** Return the default location for our torrc file.
- * DOCDOC defaults_file */
+/** Return the default location for our torrc file (if <b>defaults_file</b> is
+ * false), or for the torrc-defaults file (if <b>defaults_file</b> is true). */
 static const char *
 get_default_conf_file(int defaults_file)
 {
@@ -4396,12 +4397,21 @@ check_nickname_list(const char *lst, const char *name, char **msg)
   return r;
 }
 
-/** Learn config file name from command line arguments, or use the default,
- * DOCDOC defaults_file */
+/** Learn config file name from command line arguments, or use the default.
+ *
+ * If <b>defaults_file</b> is true, we're looking for torrc-defaults;
+ * otherwise, we're looking for the regular torrc_file.
+ *
+ * Set *<b>using_default_fname</b> to true if we're using the default
+ * configuration file name; or false if we've set it from the command line.
+ *
+ * Set *<b>ignore_missing_torrc</b> to true if we should ignore the resulting
+ * filename if it doesn't exist.
+ */
 static char *
 find_torrc_filename(int argc, char **argv,
                     int defaults_file,
-                    int *using_default_torrc, int *ignore_missing_torrc)
+                    int *using_default_fname, int *ignore_missing_torrc)
 {
   char *fname=NULL;
   int i;
@@ -4427,14 +4437,14 @@ find_torrc_filename(int argc, char **argv,
         fname = absfname;
       }
 
-      *using_default_torrc = 0;
+      *using_default_fname = 0;
       ++i;
     } else if (ignore_opt && !strcmp(argv[i],ignore_opt)) {
       *ignore_missing_torrc = 1;
     }
   }
 
-  if (*using_default_torrc) {
+  if (*using_default_fname) {
     /* didn't find one, try CONFDIR */
     const char *dflt = get_default_conf_file(defaults_file);
     if (dflt && file_status(dflt) == FN_FILE) {
@@ -4458,8 +4468,13 @@ find_torrc_filename(int argc, char **argv,
   return fname;
 }
 
-/** Load torrc from disk, setting torrc_fname if successful.
- * DOCDOC defaults_file */
+/** Load a configuration file from disk, setting torrc_fname or
+ * torrc_defaults_fname if successful.
+ *
+ * If <b>defaults_file</b> is true, load torrc-defaults; otherwise load torrc.
+ *
+ * Return the contents of the file on success, and NULL on failure.
+ */
 static char *
 load_torrc_from_disk(int argc, char **argv, int defaults_file)
 {
@@ -5455,7 +5470,10 @@ warn_nonlocal_client_ports(const smartlist_t *ports, const char *portname)
   } SMARTLIST_FOREACH_END(port);
 }
 
-/** DOCDOC */
+/** Given a list of port_cfg_t in <b>ports</b>, warn any controller port there
+ * is listening on any non-loopback address.  If <b>forbid</b> is true,
+ * then emit a stronger warning and remove the port from the list.
+ */
 static void
 warn_nonlocal_controller_ports(smartlist_t *ports, unsigned forbid)
 {
@@ -5839,10 +5857,12 @@ parse_port_config(smartlist_t *out,
   return retval;
 }
 
-/** DOCDOC */
+/** Parse a list of config_line_t for an AF_UNIX unix socket listener option
+ * from <b>cfg</b> and add them to <b>out</b>.  No fancy options are
+ * supported: the line contains nothing but the path to the AF_UNIX socket. */
 static int
-parse_socket_config(smartlist_t *out, const config_line_t *cfg,
-                    int listener_type)
+parse_unix_socket_config(smartlist_t *out, const config_line_t *cfg,
+                         int listener_type)
 {
 
   if (!out)
@@ -5928,9 +5948,9 @@ parse_ports(const or_options_t *options, int validate_only,
                         "configuration");
       goto err;
     }
-    if (parse_socket_config(ports,
-                            options->ControlSocket,
-                            CONN_TYPE_CONTROL_LISTENER) < 0) {
+    if (parse_unix_socket_config(ports,
+                                 options->ControlSocket,
+                                 CONN_TYPE_CONTROL_LISTENER) < 0) {
       *msg = tor_strdup("Invalid ControlSocket configuration");
       goto err;
     }
@@ -5980,7 +6000,8 @@ parse_ports(const or_options_t *options, int validate_only,
   return retval;
 }
 
-/** DOCDOC */
+/** Given a list of <b>port_cfg_t</b> in <b>ports</b>, check them for internal
+ * consistency and warn as appropriate. */
 static int
 check_server_ports(const smartlist_t *ports,
                    const or_options_t *options)
diff --git a/src/or/connection.c b/src/or/connection.c
index beeeb2aab0..3ff6a7104c 100644
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -1659,7 +1659,8 @@ connection_send_socks5_connect(connection_t *conn)
   conn->proxy_state = PROXY_SOCKS5_WANT_CONNECT_OK;
 }
 
-/** DOCDOC */
+/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions
+ * for documentation of its behavior. */
 static int
 connection_fetch_from_buf_socks_client(connection_t *conn,
                                        int state, char **reason)
@@ -2239,7 +2240,9 @@ global_write_bucket_low(connection_t *conn, size_t attempt, int priority)
   return 0;
 }
 
-/** DOCDOC */
+/** Helper: adjusts our bandwidth history and informs the controller as
+ * appropriate, given that we have just read <b>num_read</b> bytes and written
+ * <b>num_written</b> bytes on <b>conn</b>. */
 static void
 record_num_bytes_transferred_impl(connection_t *conn,
                              time_t now, size_t num_read, size_t num_written)
@@ -2270,7 +2273,8 @@ record_num_bytes_transferred_impl(connection_t *conn,
 }
 
 #ifdef USE_BUFFEREVENTS
-/** DOCDOC */
+/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions
+ * for documentation of its behavior. */
 static void
 record_num_bytes_transferred(connection_t *conn,
                              time_t now, size_t num_read, size_t num_written)
@@ -2592,7 +2596,8 @@ connection_get_rate_limit_totals(uint64_t *read_out, uint64_t *written_out)
   }
 }
 
-/** DOCDOC */
+/** Perform whatever operations are needed on <b>conn</b> to enable
+ * rate-limiting. */
 void
 connection_enable_rate_limiting(connection_t *conn)
 {
diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c
index ca4bf3ffe4..4c29e06f73 100644
--- a/src/or/connection_edge.c
+++ b/src/or/connection_edge.c
@@ -2673,12 +2673,12 @@ connection_ap_handshake_send_resolve(entry_connection_t *ap_conn)
   return 0;
 }
 
-/** Make an AP connection_t, make a new linked connection pair, and attach
- * one side to the conn, connection_add it, initialize it to circuit_wait,
- * and call connection_ap_handshake_attach_circuit(conn) on it.
+/** Make an AP connection_t linked to the connection_t <b>partner</b>. make a
+ * new linked connection pair, and attach one side to the conn, connection_add
+ * it, initialize it to circuit_wait, and call
+ * connection_ap_handshake_attach_circuit(conn) on it.
  *
- * Return the other end of the linked connection pair, or -1 if error.
- * DOCDOC partner.
+ * Return the newly created end of the linked connection pair, or -1 if error.
  */
 entry_connection_t *
 connection_ap_make_link(connection_t *partner,
diff --git a/src/or/connection_or.c b/src/or/connection_or.c
index 8aec5d2886..6a2f2432e2 100644
--- a/src/or/connection_or.c
+++ b/src/or/connection_or.c
@@ -2099,7 +2099,8 @@ connection_or_send_auth_challenge_cell(or_connection_t *conn)
  *
  * If <b>server</b> is false and <b>signing_key</b> is provided, calculate the
  * entire authenticator, signed with <b>signing_key</b>.
- * DOCDOC return value
+ *
+ * Return the length of the cell body on success, and -1 on failure.
  */
 int
 connection_or_compute_authenticate_cell_body(or_connection_t *conn,
diff --git a/src/or/directory.c b/src/or/directory.c
index 3d2b95565c..7531260f2c 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -3788,7 +3788,10 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code,
    * every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */
 }
 
-/* DOCDOC NM */
+/** Called when a connection to download microdescriptors has failed in whole
+ * or in part. <b>failed</b> is a list of every microdesc digest we didn't
+ * get. <b>status_code</b> is the http status code we received. Reschedule the
+ * microdesc downloads as appropriate. */
 static void
 dir_microdesc_download_failed(smartlist_t *failed,
                               int status_code)
diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c
index 3646ee6844..0f51676a0b 100644
--- a/src/or/networkstatus.c
+++ b/src/or/networkstatus.c
@@ -1183,7 +1183,8 @@ update_v2_networkstatus_cache_downloads(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Return true iff, given the options listed in <b>options</b>, <b>flavor</b>
+ *  is the flavor of a consensus networkstatus that we would like to fetch. */
 static int
 we_want_to_fetch_flavor(const or_options_t *options, int flavor)
 {
@@ -1455,7 +1456,8 @@ networkstatus_get_latest_consensus(void)
   return current_consensus;
 }
 
-/** DOCDOC */
+/** Return the latest consensus we have whose flavor matches <b>f</b>, or NULL
+ * if we don't have one. */
 networkstatus_t *
 networkstatus_get_latest_consensus_by_flavor(consensus_flavor_t f)
 {
diff --git a/src/or/or.h b/src/or/or.h
index 76681c9eea..5d620db02b 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -1251,7 +1251,8 @@ typedef struct or_connection_t {
                     * bandwidthburst. (OPEN ORs only) */
   int write_bucket; /**< When this hits 0, stop writing. Like read_bucket. */
 #else
-  /** DOCDOC */
+  /** A rate-limiting configuration object to determine how this connection
+   * set its read- and write- limits. */
   /* XXXX we could share this among all connections. */
   struct ev_token_bucket_cfg *bucket_cfg;
 #endif
@@ -1729,7 +1730,7 @@ typedef struct {
   uint16_t or_port; /**< Port for TLS connections. */
   uint16_t dir_port; /**< Port for HTTP directory connections. */
 
-  /* DOCDOC */
+  /** A router's IPv6 address, if it has one. */
   /* XXXXX187 Actually these should probably be part of a list of addresses,
    * not just a special case.  Use abstractions to access these; don't do it
    * directly. */
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 36a282a30f..db0844d2fb 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -4188,9 +4188,9 @@ any_trusted_dir_is_v1_authority(void)
 
 /** For every current directory connection whose purpose is <b>purpose</b>,
  * and where the resource being downloaded begins with <b>prefix</b>, split
- * rest of the resource into base16 fingerprints, decode them, and set the
+ * rest of the resource into base16 fingerprints (or base64 fingerprints if
+ * purpose==DIR_PURPPOSE_FETCH_MICRODESC), decode them, and set the
  * corresponding elements of <b>result</b> to a nonzero value.
- * DOCDOC purpose==microdesc
  */
 static void
 list_pending_downloads(digestmap_t *result,
@@ -4235,8 +4235,13 @@ list_pending_descriptor_downloads(digestmap_t *result, int extrainfo)
   list_pending_downloads(result, purpose, "d/");
 }
 
-/** DOCDOC */
-/*XXXX NM should use digest256, if one comes into being. */
+/** For every microdescriptor we are currently downloading by descriptor
+ * digest, set result[d] to (void*)1.   (Note that microdescriptor digests
+ * are 256-bit, and digestmap_t only holds 160-bit digests, so we're only
+ * getting the first 20 bytes of each digest here.)
+ *
+ * XXXX Let there be a digestmap256_t, and use that instead.
+ */
 void
 list_pending_microdesc_downloads(digestmap_t *result)
 {
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index 781c57897d..d86c0cfa85 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -4169,7 +4169,10 @@ _find_by_keyword(smartlist_t *s, directory_keyword keyword,
   return tok;
 }
 
-/** DOCDOC */
+/** If there are any directory_token_t entries in <b>s</b> whose keyword is
+ * <b>k</b>, return a newly allocated smartlist_t containing all such entries,
+ * in the same order in which they occur in <b>s</b>.  Otherwise return
+ * NULL. */
 static smartlist_t *
 find_all_by_keyword(smartlist_t *s, directory_keyword k)
 {