[or-cvs] r17662: {tor} Resolve many DOCDOCs. (in tor/trunk/src: common or)
nickm at seul.org
nickm at seul.org
Wed Dec 17 22:58:20 UTC 2008
Author: nickm
Date: 2008-12-17 17:58:20 -0500 (Wed, 17 Dec 2008)
New Revision: 17662
Modified:
tor/trunk/src/common/address.c
tor/trunk/src/common/log.c
tor/trunk/src/common/memarea.c
tor/trunk/src/common/tortls.c
tor/trunk/src/common/tortls.h
tor/trunk/src/or/config.c
tor/trunk/src/or/connection_edge.c
tor/trunk/src/or/directory.c
tor/trunk/src/or/dns.c
tor/trunk/src/or/eventdns.c
tor/trunk/src/or/geoip.c
tor/trunk/src/or/relay.c
tor/trunk/src/or/rephist.c
tor/trunk/src/or/routerlist.c
Log:
Resolve many DOCDOCs.
Modified: tor/trunk/src/common/address.c
===================================================================
--- tor/trunk/src/common/address.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/common/address.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -630,7 +630,7 @@
memcpy(dest->addr.in6_addr.s6_addr, ipv6_bytes, 16);
}
-/** DOCDOC */
+/** Set <b>dest</b> equal to the IPv6 address in the in6_addr <b>in6</b>. */
void
tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6)
{
Modified: tor/trunk/src/common/log.c
===================================================================
--- tor/trunk/src/common/log.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/common/log.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -53,7 +53,8 @@
int is_temporary; /**< Boolean: close after initializing logging subsystem.*/
int is_syslog; /**< Boolean: send messages to syslog. */
log_callback callback; /**< If not NULL, send messages to this function. */
- log_severity_list_t *severities; /**< DOCDOC */
+ log_severity_list_t *severities; /**< Which severity of messages should we
+ * log for each log domain? */
} logfile_t;
static void log_free(logfile_t *victim);
@@ -415,7 +416,7 @@
}
#endif
-/** DOCDOC */
+/** Free all storage held by <b>victim</b>. */
static void
log_free(logfile_t *victim)
{
@@ -730,14 +731,17 @@
return sev_to_string(level);
}
-/** DOCDOC */
+/** NULL-terminated array of names for log domains such that domain_list[dom]
+ * is a description of <b>dom</b>. */
static const char *domain_list[] = {
"GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM",
"HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV",
"OR", "EDGE", "ACCT", "HIST", NULL
};
-/** DOCDOC */
+/** Return the log domain for which <b>domain</b> is the name, or 0 if there
+ * is no such name. */
+/*XXXX021 0 could mean "no such domain" or LD_GENERAL. Fix that. */
static log_domain_mask_t
parse_log_domain(const char *domain)
{
Modified: tor/trunk/src/common/memarea.c
===================================================================
--- tor/trunk/src/common/memarea.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/common/memarea.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -138,7 +138,7 @@
area->first->next_mem = area->first->u.mem;
}
-/** DOCDOC */
+/** Remove all unused memarea chunks from the internal freelist. */
void
memarea_clear_freelist(void)
{
Modified: tor/trunk/src/common/tortls.c
===================================================================
--- tor/trunk/src/common/tortls.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/common/tortls.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -1442,7 +1442,11 @@
return 1;
}
-/** DOCDOC */
+/** Examine the amount of memory used and available for buffers in <b>tls</b>.
+ * Set *<b>rbuf_capacity</b> to the amount of storage allocated for the read
+ * buffer and *<b>rbuf_bytes</b> to the amount actually used.
+ * Set *<b>wbuf_capacity</b> to the amount of storage allocated for the write
+ * buffer and *<b>wbuf_bytes</b> to the amount actually used. */
void
tor_tls_get_buffer_sizes(tor_tls_t *tls,
int *rbuf_capacity, int *rbuf_bytes,
Modified: tor/trunk/src/common/tortls.h
===================================================================
--- tor/trunk/src/common/tortls.h 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/common/tortls.h 2008-12-17 22:58:20 UTC (rev 17662)
@@ -33,7 +33,8 @@
#define TOR_TLS_WANTWRITE -1
#define TOR_TLS_DONE 0
-/** DOCDOC XXXX021 also rename me. */
+/** Collection of case statements for all TLS errors that are not due to
+ * underlying IO failure. */
#define CASE_TOR_TLS_ERROR_ANY_NONIO \
case TOR_TLS_ERROR_MISC: \
case TOR_TLS_ERROR_CONNREFUSED: \
Modified: tor/trunk/src/or/config.c
===================================================================
--- tor/trunk/src/or/config.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/config.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -1191,7 +1191,8 @@
return r;
}
-/** DOCDOC */
+/** If we need to have a GEOIP ip-to-country map to run with our configured
+ * options, return 1 and set *<b>reason_out</b> to a description of why. */
int
options_need_geoip_info(or_options_t *options, const char **reason_out)
{
Modified: tor/trunk/src/or/connection_edge.c
===================================================================
--- tor/trunk/src/or/connection_edge.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/connection_edge.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -1361,6 +1361,11 @@
return 0;
}
+/** How many times do we try connecting with an exit configured via
+ * TrackHostExits before concluding that it won't work any more and trying a
+ * different one? */
+#define TRACKHOSTEXITS_RETRIES 5
+
/** Connection <b>conn</b> just finished its socks handshake, or the
* controller asked us to take care of it. If <b>circ</b> is defined,
* then that's where we'll want to attach it. Otherwise we have to
@@ -1500,8 +1505,6 @@
if (s) {
if (s[1] != '\0') {
conn->chosen_exit_name = tor_strdup(s+1);
-/* DOCDOC */
-#define TRACKHOSTEXITS_RETRIES 5
if (remapped_to_exit) /* 5 tries before it expires the addressmap */
conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES;
*s = 0;
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/directory.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -2179,13 +2179,13 @@
}
#ifdef INSTRUMENT_DOWNLOADS
-/** Map used to keep track of how much data we've up/downloaded in what kind
- * of request. Maps from request type to pointer to uint64_t. */
typedef struct request_t {
- uint64_t bytes;
- uint64_t count;
+ uint64_t bytes; /**< How many bytes have we transferred? */
+ uint64_t count; /**< How many requests have we made? */
} request_t;
+/** Map used to keep track of how much data we've up/downloaded in what kind
+ * of request. Maps from request type to pointer to request_t. */
static strmap_t *request_map = NULL;
static void
@@ -2222,7 +2222,7 @@
tor_free(key);
}
-/** DOCDOC */
+/** Helper: initialize the request map to instrument downloads. */
static void
ensure_request_map_initialized(void)
{
@@ -3394,6 +3394,8 @@
* every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */
}
+/** Helper. Compare two fp_pair_t objects, and return -1, 0, or 1 as
+ * appropriate. */
static int
_compare_pairs(const void **a, const void **b)
{
@@ -3405,7 +3407,10 @@
return memcmp(fp1->second, fp2->second, DIGEST_LEN);
}
-/** DOCDOC */
+/** Divide a string <b>res</b> of the form FP1-FP2+FP3-FP4...[.z], where each
+ * FP is a hex-encoded fingerprint, into a sequence of distinct sorted
+ * fp_pair_t. Skip malformed pairs. On success, return 0 and add those
+ * fp_pair_t into <b>pairs_out</b>. On failure, return -1. */
int
dir_split_resource_into_fingerprint_pairs(const char *res,
smartlist_t *pairs_out)
Modified: tor/trunk/src/or/dns.c
===================================================================
--- tor/trunk/src/or/dns.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/dns.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -229,7 +229,8 @@
return 0;
}
-/**DOCDOC*/
+/** Return true iff the most recent attempt to initialize the DNS subsystem
+ * failed. */
int
has_dns_init_failed(void)
{
Modified: tor/trunk/src/or/eventdns.c
===================================================================
--- tor/trunk/src/or/eventdns.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/eventdns.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -307,7 +307,7 @@
/* number of timeouts in a row before we consider this server to be down */
static int global_max_nameserver_timeout = 3;
-/* DOCDOC */
+/* true iff we should use the 0x20 hack. */
static int global_randomize_case = 1;
/* These are the timeout values for nameservers. If we find a nameserver is down */
Modified: tor/trunk/src/or/geoip.c
===================================================================
--- tor/trunk/src/or/geoip.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/geoip.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -23,10 +23,12 @@
intptr_t country; /**< An index into geoip_countries */
} geoip_entry_t;
-/** DOCDOC */
+/** For how many periods should we remember per-country request history? */
#define REQUEST_HIST_LEN 3
+/** How long are the periods for which we should remember request history? */
#define REQUEST_HIST_PERIOD (8*60*60)
+/** A per-country record for GeoIP request history */
typedef struct geoip_country_t {
char countrycode[3];
uint32_t n_v2_ns_requests[REQUEST_HIST_LEN];
@@ -269,8 +271,10 @@
/** Time at which we started tracking client IP history. */
static time_t client_history_starts = 0;
-/** DOCDOC */
+/** When did the current period of checking per-country request history
+ * start? */
static time_t current_request_period_starts = 0;
+/** How many older request periods are we remembering? */
static int n_old_request_periods = 0;
/** Hashtable helper: compute a hash of a clientmap_entry_t. */
@@ -312,7 +316,7 @@
#endif
}
- /* DOCDOC */
+ /* Rotate the current request period. */
while (current_request_period_starts + REQUEST_HIST_PERIOD < now) {
if (!geoip_countries)
geoip_countries = smartlist_create();
@@ -430,7 +434,8 @@
return strcmp(a->country, b->country);
}
-/*DOCDOC*/
+/** How long do we have to have observed per-country request history before we
+ * are willing to talk about it? */
#define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
static INLINE unsigned
@@ -529,7 +534,9 @@
return result;
}
-/**DOCDOC*/
+/** Return a newly allocated string holding the per-country request history
+ * for <b>action</b> in a format suitable for an extra-info document, or NULL
+ * on failure. */
char *
geoip_get_request_history(time_t now, geoip_client_action_t action)
{
Modified: tor/trunk/src/or/relay.c
===================================================================
--- tor/trunk/src/or/relay.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/relay.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -1844,7 +1844,13 @@
}
}
-/** DOCDOC */
+/** Append an encoded value of <b>addr<b> to <b>payload_out</b>, which must
+ * have at least 18 bytes of free space. The encoding is, as specified in
+ * tor-spec.txt:
+ * RESOLVED_TYPE_IPV4 or RESOLVED_TYPE_IPV6 [1 byte]
+ * LENGTH [1 byte]
+ * ADDRESS [length bytes]
+ * Return the number of bytes added, or -1 on error */
int
append_address_to_payload(char *payload_out, const tor_addr_t *addr)
{
@@ -1867,7 +1873,10 @@
}
}
-/** DODOC */
+/** Given <b>payload_len</b> bytes at <b>payload</b>, starting with an address
+ * encoded as by append_address_to_payload(), try to decode the address into
+ * *<b>addr_out</b>. Return the next byte in the payload after the address on
+ * success, or NULL on failure. */
const char *
decode_address_from_payload(tor_addr_t *addr_out, const char *payload,
int payload_len)
Modified: tor/trunk/src/or/rephist.c
===================================================================
--- tor/trunk/src/or/rephist.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/rephist.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -777,7 +777,8 @@
return -1;
}
-/** DOCDOC */
+/** Format the current tracked status of the router in <b>hist</b> at time
+ * <b>now</b> for analysis; return it in a newly allocated string. */
static char *
rep_hist_format_router_status(or_history_t *hist, time_t now)
{
@@ -821,12 +822,17 @@
return tor_strdup(buf);
}
-/* DOCDOC */
+/** The last stability analysis document that we created, or NULL if we never
+ * have created one. */
static char *last_stability_doc = NULL;
+/** The last time we created a stability analysis document, or 0 if we never
+ * have created one. */
static time_t built_last_stability_doc_at = 0;
+/** Shortest allowable time between building two stability documents. */
#define MAX_STABILITY_DOC_BUILD_RATE (3*60)
-/* DOCDOC */
+/** Return a pointer to a NUL-terminated document describing our view of the
+ * stability of the routers we've been tracking. Return NULL on failure. */
const char *
rep_hist_get_router_stability_doc(time_t now)
{
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2008-12-17 22:58:14 UTC (rev 17661)
+++ tor/trunk/src/or/routerlist.c 2008-12-17 22:58:20 UTC (rev 17662)
@@ -4808,12 +4808,18 @@
* a router belongs to the set if it is _rejected_ by this policy. */
smartlist_t *policies;
- /** DOCDOC */
+ /** A human-readable description of what this routerset is for. Used in
+ * log messages. */
char *description;
- /** DOCDOC */
+ /** A list of the country codes in this set. */
smartlist_t *country_names;
+ /** Total number of countries we knew about when we built <b>countries</b>. */
int n_countries;
+ /** Bit array mapping the return value of geoip_get_country() to 1 iff the
+ * country is a member of this routerset. Note that we MUST call
+ * routerset_refresh_countries() whenever the geoip country list is
+ * reloaded. */
bitarray_t *countries;
};
@@ -4830,7 +4836,8 @@
return result;
}
-/** DOCDOC */
+/** If <b>c</b> is a country code in the form {cc}, return a newly allocated
+ * string holding the "cc" part. Else, return NULL. */
static char *
routerset_get_countryname(const char *c)
{
@@ -4981,14 +4988,15 @@
smartlist_len(set->policies) == 0;
}
-/** DOCDOC */
+/** Return true iff we need a GeoIP IP-to-country database to make sense of
+ * <b>set</b>. */
int
routerset_needs_geoip(const routerset_t *set)
{
return set && smartlist_len(set->country_names);
}
-/** DOCDOC */
+/** Return true iff there are no entries in <b>set</b>. */
static int
routerset_is_empty(const routerset_t *set)
{
@@ -4996,8 +5004,12 @@
}
/** Helper. Return true iff <b>set</b> contains a router based on the other
- * provided fields. Return higher values for more specific subentries.
- (If country is -1, then we take the country from addr.) */
+ * provided fields. Return higher values for more specific subentries: a
+ * single router is more specific than an address range of routers, which is
+ * more specific in turn than a country code.
+ *
+ * (If country is -1, then we take the country
+ * from addr.) */
static int
routerset_contains(const routerset_t *set, const tor_addr_t *addr,
uint16_t orport,
@@ -5102,9 +5114,10 @@
}
}
-/** Add to <b>target</b> every node from <b>source</b> that is in
- * <b>include</b> not excluded in a more specific fashion by
- * <b>exclude</b>. DOCDOC */
+/** Add to <b>target</b> every routerinfo_t from <b>source</b> that is in
+ * <b>include</b>, but not excluded in a more specific fashion by
+ * <b>exclude</b>. If <b>running_only</b>, only include running routers.
+ */
void
routersets_get_disjunction(smartlist_t *target,
const smartlist_t *source,
@@ -5217,14 +5230,15 @@
tor_free(routerset);
}
-/** DOCDOC */
+/** Refresh the country code of <b>ri</b>. This function MUST be called on
+ * each router when the GeoIP database is reloaded, and on all new routers. */
void
routerinfo_set_country(routerinfo_t *ri)
{
ri->country = geoip_get_country_by_ip(ri->addr);
}
-/** DOCDOC */
+/** Set the country code of all routers in the routerlist. */
void
routerlist_refresh_countries(void)
{
More information about the tor-commits
mailing list