[tor-commits] [tor/master] Resolve all currently pending DOCDOC items in master
nickm at torproject.org
nickm at torproject.org
Mon Jun 4 23:11:21 UTC 2012
commit f68c042637d253dfb3160357ba2b9ec530cb48ef
Author: Nick Mathewson <nickm at torproject.org>
Date: Mon Jun 4 18:50:13 2012 -0400
Resolve all currently pending DOCDOC items in master
---
src/common/compat.c | 3 +-
src/common/util.c | 12 +++++++-
src/common/util.h | 4 ++-
src/or/config.c | 59 +++++++++++++++++++++++++++++++--------------
src/or/connection.c | 13 +++++++---
src/or/connection_edge.c | 10 ++++----
src/or/connection_or.c | 3 +-
src/or/directory.c | 5 +++-
src/or/networkstatus.c | 6 +++-
src/or/or.h | 5 ++-
src/or/routerlist.c | 13 +++++++---
src/or/routerparse.c | 5 +++-
12 files changed, 95 insertions(+), 43 deletions(-)
diff --git a/src/common/compat.c b/src/common/compat.c
index 0931061..49a4afe 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 e7979d8..b3145ae 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 36601fa..ae40898 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 8a19ed6..5f5960f 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 beeeb2a..3ff6a71 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 ca4bf3f..4c29e06 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 8aec5d2..6a2f243 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 3d2b955..7531260 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 3646ee6..0f51676 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 76681c9..5d620db 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 36a282a..db0844d 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 781c578..d86c0cf 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)
{
More information about the tor-commits
mailing list