[or-cvs] r9596: Fix 35 remaining DOCDOC comments. Yowza. (in tor/trunk: . src/common src/or)
nickm at seul.org
nickm at seul.org
Fri Feb 16 20:39:46 UTC 2007
Author: nickm
Date: 2007-02-16 15:39:37 -0500 (Fri, 16 Feb 2007)
New Revision: 9596
Modified:
tor/trunk/
tor/trunk/src/common/tortls.c
tor/trunk/src/common/util.c
tor/trunk/src/or/circuitbuild.c
tor/trunk/src/or/circuitlist.c
tor/trunk/src/or/circuituse.c
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/main.c
tor/trunk/src/or/policies.c
tor/trunk/src/or/router.c
Log:
r11832 at catbus: nickm | 2007-02-16 15:31:59 -0500
Fix 35 remaining DOCDOC comments. Yowza.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r11832] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/src/common/tortls.c
===================================================================
--- tor/trunk/src/common/tortls.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/common/tortls.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -103,7 +103,8 @@
}
}
-/** DOCDOC */
+/** Convert an errno (or a WSAerrno on windows) into a TOR_TLS_* error
+ * code. */
static int
tor_errno_to_tls_error(int e)
{
@@ -206,7 +207,7 @@
}
}
-/** DOCDOC */
+/** Free all global TLS structures. */
void
tor_tls_free_all(void)
{
@@ -672,7 +673,7 @@
return 1;
}
-/** DOCDOC */
+/** Warn that a certificate lifetime extends through a certain range. */
static void
log_cert_lifetime(X509 *cert, const char *problem)
{
Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/common/util.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -862,9 +862,9 @@
a->tv_usec %= 1000000;
}
-/** DOCDOC */
+/** Yield true iff <b>y</b> is a leap-year */
#define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
-/** DOCDOC */
+/** Helper: Return the number of leap-days between Jan 1, y1 and Jan 1, y2. */
static int
n_leapdays(int y1, int y2)
{
@@ -1957,11 +1957,12 @@
#ifndef MS_WINDOWS
/* Based on code contributed by christian grothoff */
-/** DOCDOC */
+/** True iff we've called start_daemon. */
static int start_daemon_called = 0;
-/** DOCDOC */
+/** True iff we've called finish_daemon. */
static int finish_daemon_called = 0;
-/** DOCDOC */
+/** Socketpair used to communicate between parent and child process while
+ * daemonizing. */
static int daemon_filedes[2];
/** Start putting the process into daemon mode: fork and drop all resources
* except standard fds. The parent process never returns, but stays around
Modified: tor/trunk/src/or/circuitbuild.c
===================================================================
--- tor/trunk/src/or/circuitbuild.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/circuitbuild.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -1110,7 +1110,8 @@
return 0;
}
-/* DOCDOC */
+/** Return true iff <b>conn</b> is waiting for a general circuit to be
+ * built. */
static int
ap_stream_wants_exit_attention(connection_t *conn)
{
Modified: tor/trunk/src/or/circuitlist.c
===================================================================
--- tor/trunk/src/or/circuitlist.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/circuitlist.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -48,14 +48,15 @@
return a->or_conn == b->or_conn && a->circ_id == b->circ_id;
}
-/** DOCDOC */
+/** Helper: return a hash based on circuit ID and the pointer value of
+ * or_conn in <b>a</b>. */
static INLINE unsigned int
_orconn_circid_entry_hash(orconn_circid_circuit_map_t *a)
{
return (((unsigned)a->circ_id)<<16) ^ (unsigned)(uintptr_t)(a->or_conn);
}
-/** DOCDOC */
+/** Map from [orconn,circid] to circuit. */
static HT_HEAD(orconn_circid_map, orconn_circid_circuit_map_t)
orconn_circid_circuit_map = HT_INITIALIZER();
HT_PROTOTYPE(orconn_circid_map, orconn_circid_circuit_map_t, node,
@@ -319,7 +320,8 @@
return circ;
}
-/** DOCDOC */
+/** Allocate a new or_circuit_t, connected to <b>p_conn</b> as
+ * <b>p_circ_id</b>. If <b>p_conn</b> is NULL, the circuit is unattached. */
or_circuit_t *
or_circuit_new(uint16_t p_circ_id, or_connection_t *p_conn)
{
Modified: tor/trunk/src/or/circuituse.c
===================================================================
--- tor/trunk/src/or/circuituse.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/circuituse.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -566,10 +566,11 @@
}
}
-/** DOCDOC */
+/** Number of circuits to open at once when testing our bandwidth. */
#define NUM_PARALLEL_TESTING_CIRCS 4
-/** DOCDOC */
+/** True iff we've ever opened enough testing circuits to test our
+ * bandwidth. */
static int have_performed_bandwidth_test = 0;
/** Reset have_performed_bandwidth_test, so we'll start building
@@ -776,7 +777,8 @@
* circuit_launch_new and circuit_*_failure_count.
*/
static int n_circuit_failures = 0;
-/** DOCDOC */
+/** Before the last time we called circuit_reset_failure_count(), were
+ * there a lot of failures? */
static int did_circs_fail_last_period = 0;
/** Don't retry launching a new circuit if we try this many times with no
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/dirserv.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -52,23 +52,24 @@
#define FP_REJECT 4 /**< We will not publish this router. */
#define FP_BADEXIT 8 /**< We'll tell clients not to use this as an exit. */
-/** DOCDOC */
+/** Encapsulate a nickname and an FP_* status; target of status_by_digest
+ * map. */
typedef struct router_status_t {
char nickname[MAX_NICKNAME_LEN+1];
uint32_t status;
} router_status_t;
/** List of nickname-\>identity fingerprint mappings for all the routers
- * that we name. Used to prevent router impersonation. DODDOC */
+ * that we name. Used to prevent router impersonation. */
typedef struct authdir_config_t {
strmap_t *fp_by_name; /* Map from lc nickname to fingerprint */
- digestmap_t *status_by_digest; /* Map from digest to FP_x mask */
+ digestmap_t *status_by_digest; /* Map from digest to router_status_t. */
} authdir_config_t;
/** Should be static; exposed for testing */
authdir_config_t *fingerprint_list = NULL;
-/** DOCDOC */
+/** Allocate and return a new, empty, authdir_config_t. */
static authdir_config_t *
authdir_config_new(void)
{
@@ -576,11 +577,12 @@
}
}
-/** DOCDOC */
+/** Helper: return true iff the boolean values of <b>a</b> and <b>b</b> are
+ * different. */
static INLINE int
bool_neq(int a, int b)
{
- return (a && !b) || (!a && b);
+ return (a) ? !b : b;
}
/** Remove all descriptors whose nicknames or fingerprints no longer
@@ -1338,7 +1340,8 @@
/** For authoritative directories: the current (v2) network status */
static cached_dir_t *the_v2_networkstatus = NULL;
-/** DOCDOC */
+/** Return true iff our opinion of the routers has been stale for long
+ * enough that we should generate a new network status doc. */
static int
should_generate_v2_networkstatus(void)
{
@@ -1488,11 +1491,11 @@
static cached_dir_t *
generate_v2_networkstatus(void)
{
-/** DOCDOC */
+/** Longest status flag name that we generate. */
#define LONGEST_STATUS_FLAG_NAME_LEN 9
-/** DOCDOC */
-#define N_STATUS_FLAGS 9
-/** DOCDOC */
+/** Maximum number of status flags we'll apply to one router. */
+#define N_STATUS_FLAGS 10
+/** 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+ \
Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/main.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -58,7 +58,8 @@
/** Array of all open connections. The first n_conns elements are valid. */
static connection_t *connection_array[MAXCONNECTIONS+1] =
{ NULL };
-/** DOCDOC */
+/** List of connections that have been marked for close and need to be freed
+ * and removed from connection_array. */
static smartlist_t *closeable_connection_lst = NULL;
static int n_conns=0; /**< Number of connections currently active. */
@@ -818,7 +819,7 @@
if (any_trusted_dir_is_v1_authority())
directory_get_from_dirserver(DIR_PURPOSE_FETCH_DIR, NULL, 1);
}
-/** DOCDOC */
+/** How often do we (as a cache) fetch a new V1 directory? */
#define V1_DIR_FETCH_PERIOD (6*60*60)
time_to_fetch_directory = now + V1_DIR_FETCH_PERIOD;
}
@@ -828,7 +829,7 @@
if (!authdir_mode(options) || !options->V1AuthoritativeDir) {
directory_get_from_dirserver(DIR_PURPOSE_FETCH_RUNNING_LIST, NULL, 1);
}
-/** DOCDOC */
+/** How often do we (as a cache) fetch a new V1 runningrouters document? */
#define V1_RUNNINGROUTERS_FETCH_PERIOD (30*60)
time_to_fetch_running_routers = now + V1_RUNNINGROUTERS_FETCH_PERIOD;
@@ -955,9 +956,9 @@
}
}
-/** DOCDOC */
+/** Libevent timer: used to invoke second_elapsed_callback once per second. */
static struct event *timeout_event = NULL;
-/** DOCDOC */
+/** Number of libevent errors in the last second: we die if we get too many. */
static int n_libevent_errors = 0;
/** Libevent callback: invoked once every second. */
Modified: tor/trunk/src/or/policies.c
===================================================================
--- tor/trunk/src/or/policies.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/policies.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -156,7 +156,8 @@
}
}
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make an OR connection to
+ * addr:port. */
int
fascist_firewall_allows_address_or(uint32_t addr, uint16_t port)
{
@@ -164,7 +165,8 @@
reachable_or_addr_policy);
}
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make a directory
+ * connection to addr:port. */
int
fascist_firewall_allows_address_dir(uint32_t addr, uint16_t port)
{
Modified: tor/trunk/src/or/router.c
===================================================================
--- tor/trunk/src/or/router.c 2007-02-16 20:01:21 UTC (rev 9595)
+++ tor/trunk/src/or/router.c 2007-02-16 20:39:37 UTC (rev 9596)
@@ -28,13 +28,15 @@
*/
static tor_mutex_t *key_lock=NULL;
static time_t onionkey_set_at=0; /**< When was onionkey last changed? */
-/** DOCDOC */
+/** Current private onionskin decryption key: used to decode CREATE cells. */
static crypto_pk_env_t *onionkey=NULL;
-/** DOCDOC */
+/** Previous private onionskin decription key: used to decode CREATE cells
+ * generated by client that have an older version of our descriptor. */
static crypto_pk_env_t *lastonionkey=NULL;
-/** DOCDOC */
+/** Private "identity key": used to sign directory info and TLS
+ * certificates. Never changes. */
static crypto_pk_env_t *identitykey=NULL;
-/** DOCDOC */
+/** Digest of identitykey. */
static char identitykey_digest[DIGEST_LEN];
/** Replace the current onion key with <b>k</b>. Does not affect lastonionkey;
@@ -999,7 +1001,8 @@
}
}
-/** DOCDOC */
+/** Note at log level severity that our best guess of address has changed from
+ * <b>prev</b> to <b>cur</b> */
static void
log_addr_has_changed(int severity, uint32_t prev, uint32_t cur)
{
@@ -1050,7 +1053,8 @@
}
}
-/** DOCDOC */
+/** The most recently guessed value of our IP address, from directory
+ * headers. */
static uint32_t last_guessed_ip = 0;
/** A directory authority told us our IP address is <b>suggestion</b>.
More information about the tor-commits
mailing list