[or-cvs] r17734: {tor} Fix most DOCDOCs remaining and/or added by redox. (in tor/trunk/src: common or)
nickm at seul.org
nickm at seul.org
Mon Dec 22 17:53:25 UTC 2008
Author: nickm
Date: 2008-12-22 12:53:04 -0500 (Mon, 22 Dec 2008)
New Revision: 17734
Modified:
tor/trunk/src/common/address.h
tor/trunk/src/common/compat.c
tor/trunk/src/common/container.c
tor/trunk/src/common/crypto.c
tor/trunk/src/common/crypto.h
tor/trunk/src/common/log.c
tor/trunk/src/common/memarea.c
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/directory.c
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/dirvote.c
tor/trunk/src/or/dns.c
tor/trunk/src/or/geoip.c
tor/trunk/src/or/main.c
tor/trunk/src/or/policies.c
tor/trunk/src/or/relay.c
tor/trunk/src/or/router.c
tor/trunk/src/or/routerlist.c
tor/trunk/src/or/routerparse.c
tor/trunk/src/or/test.c
Log:
Fix most DOCDOCs remaining and/or added by redox.
Modified: tor/trunk/src/common/address.h
===================================================================
--- tor/trunk/src/common/address.h 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/address.h 2008-12-22 17:53:04 UTC (rev 17734)
@@ -17,8 +17,10 @@
#include "torint.h"
#include "compat.h"
-/* DOCDOC maskbits_t */
+/** The number of bits from an address to consider while doing a masked
+ * comparison. */
typedef uint8_t maskbits_t;
+
struct in_addr;
/** Holds an IPv4 or IPv6 address. (Uses less memory than struct
* sockaddr_storage.) */
@@ -31,20 +33,30 @@
} addr;
} tor_addr_t;
-/* DOCDOC*/
+/** Return an IPv4 address in network order for <b>a</b>, or 0 if
+ * <b>a</b> is not an IPv4 address. */
static INLINE uint32_t tor_addr_to_ipv4n(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_ipv4h */
+/** Return an IPv4 address in host order for <b>a</b>, or 0 if
+ * <b>a</b> is not an IPv4 address. */
static INLINE uint32_t tor_addr_to_ipv4h(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_mapped_ipv4h */
+/* Given an IPv6 address, return its mapped IPv4 address in host order, or
+ * 0 if <b>a</b> is not an IPv6 address.
+ *
+ * (Does not check whether the address is really a mapped address */
static INLINE uint32_t tor_addr_to_mapped_ipv4h(const tor_addr_t *a);
-/* DOCDOC tor_addr_family */
+/** Return the address family of <b>a</b>. Possible values are:
+ * AF_INET6, AF_INET, AF_UNSPEC. */
static INLINE sa_family_t tor_addr_family(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_in */
+/** Return an in_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not
+ * an IPv4 address. */
static INLINE const struct in_addr *tor_addr_to_in(const tor_addr_t *a);
-/* DOCDOC tor_addr_to_in6 */
+/** Return an in6_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not
+ * an IPv6 address. */
static INLINE const struct in6_addr *tor_addr_to_in6(const tor_addr_t *a);
-/* DOCDOC tor_addr_eq_ipv4h */
+/** Return true iff <b>a</b> is an IPv4 address equal to the host-ordered
+ * address in <b>u</b>. */
static INLINE int tor_addr_eq_ipv4h(const tor_addr_t *a, uint32_t u);
+
socklen_t tor_addr_to_sockaddr(const tor_addr_t *a, uint16_t port,
struct sockaddr *sa_out, socklen_t len);
int tor_addr_from_sockaddr(tor_addr_t *a, const struct sockaddr *sa,
@@ -74,7 +86,7 @@
static INLINE uint32_t
tor_addr_to_mapped_ipv4h(const tor_addr_t *a)
{
- return ntohl(tor_addr_to_in6_addr32(a)[3]);
+ return a->family == AF_INET6 ? ntohl(tor_addr_to_in6_addr32(a)[3]) : 0;
}
static INLINE sa_family_t
tor_addr_family(const tor_addr_t *a)
Modified: tor/trunk/src/common/compat.c
===================================================================
--- tor/trunk/src/common/compat.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/compat.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -1831,7 +1831,8 @@
#elif defined(USE_PTHREADS)
static pthread_mutexattr_t attr_reentrant;
static int threads_initialized = 0;
-/* DOCDOC tor_mutex_init */
+/** Initialize <b>mutex</b> so it can be locked. Every mutex must be set
+ * up eith tor_mutex_init() or tor_mutex_new(); not both. */
void
tor_mutex_init(tor_mutex_t *mutex)
{
@@ -1868,7 +1869,9 @@
tor_fragile_assert();
}
}
-/* DOCDOC tor_mutex_uninit */
+/** Clean up the mutex <b>m</b> so that it no longer uses any system
+ * resources. Does not free <b>m</b>. This function must only be called on
+ * mutexes from tor_mutex_init(). */
void
tor_mutex_uninit(tor_mutex_t *m)
{
@@ -1894,7 +1897,7 @@
#endif
#ifdef TOR_IS_MULTITHREADED
-/* DOCDOC tor_mutex_new */
+/** Return a newly allocated, ready-for-use mutex. */
tor_mutex_t *
tor_mutex_new(void)
{
@@ -1902,7 +1905,7 @@
tor_mutex_init(m);
return m;
}
-/* DOCDOC tor_mutex_free */
+/** Release all storage and system resources held by <b>m</b>. */
void
tor_mutex_free(tor_mutex_t *m)
{
Modified: tor/trunk/src/common/container.c
===================================================================
--- tor/trunk/src/common/container.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/container.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -687,7 +687,10 @@
smartlist_uniq(sl, _compare_digests, _tor_free);
}
-/* DOCDOC DEFINE_MAP_STRUCTS */
+/** Helper: Declare an entry type and a map type to implement a mapping using
+ * ht.h. The map type will be called <b>maptype</b>. The key part of each
+ * entry is declared using the C declaration <b>keydecl</b>. All functions
+ * and types associated with the map get prefixed with <b>prefix</b> */
#define DEFINE_MAP_STRUCTS(maptype, keydecl, prefix) \
typedef struct prefix ## entry_t { \
HT_ENTRY(prefix ## entry_t) node; \
@@ -698,9 +701,7 @@
HT_HEAD(prefix ## impl, prefix ## entry_t) head; \
}
-/* DOCDOC DEFINE_MAP_STRUCTS */
DEFINE_MAP_STRUCTS(strmap_t, char *key, strmap_);
-/* DOCDOC DEFINE_MAP_STRUCTS */
DEFINE_MAP_STRUCTS(digestmap_t, char key[DIGEST_LEN], digestmap_);
/** Helper: compare strmap_entry_t objects by key value. */
@@ -1007,7 +1008,7 @@
return HT_START(strmap_impl, &map->head);
}
-/* DOCDOC digestmap_iter_init */
+/** Start iterating through <b>map</b>. See strmap_iter_init() for example. */
digestmap_iter_t *
digestmap_iter_init(digestmap_t *map)
{
@@ -1015,8 +1016,8 @@
return HT_START(digestmap_impl, &map->head);
}
-/** Advance the iterator <b>iter</b> for map a single step to the next entry.
- */
+/** Advance the iterator <b>iter</b> for <b>map</b> a single step to the next
+ * entry, and return its new value. */
strmap_iter_t *
strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
{
@@ -1025,7 +1026,8 @@
return HT_NEXT(strmap_impl, &map->head, iter);
}
-/* DOCDOC digestmap_iter_next */
+/** Advance the iterator <b>iter</b> for map a single step to the next entry,
+ * and return its new value. */
digestmap_iter_t *
digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter)
{
@@ -1035,7 +1037,7 @@
}
/** Advance the iterator <b>iter</b> a single step to the next entry, removing
- * the current entry.
+ * the current entry, and return its new value.
*/
strmap_iter_t *
strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
@@ -1051,7 +1053,9 @@
return iter;
}
-/* DOCDOC digestmap_iter_next_rmv */
+/** Advance the iterator <b>iter</b> a single step to the next entry, removing
+ * the current entry, and return its new value.
+ */
digestmap_iter_t *
digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter)
{
@@ -1065,8 +1069,8 @@
return iter;
}
-/** Set *keyp and *valp to the current entry pointed to by iter.
- */
+/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by
+ * iter. */
void
strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
{
@@ -1078,7 +1082,8 @@
*valp = (*iter)->val;
}
-/* DOCDOC digestmap_iter_get */
+/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by
+ * iter. */
void
digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp)
{
@@ -1090,14 +1095,16 @@
*valp = (*iter)->val;
}
-/** Return true iff iter has advanced past the last entry of map.
- */
+/** Return true iff <b>iter</b> has advanced past the last entry of
+ * <b>map</b>. */
int
strmap_iter_done(strmap_iter_t *iter)
{
return iter == NULL;
}
-/* DOCDOC digestmap_iter_done */
+
+/** Return true iff <b>iter</b> has advanced past the last entry of
+ * <b>map</b>. */
int
digestmap_iter_done(digestmap_iter_t *iter)
{
@@ -1124,7 +1131,11 @@
HT_CLEAR(strmap_impl, &map->head);
tor_free(map);
}
-/* DOCDOC digestmap_free */
+
+/** Remove all entries from <b>map</b>, and deallocate storage for those
+ * entries. If free_val is provided, it is invoked on every value in
+ * <b>map</b>.
+ */
void
digestmap_free(digestmap_t *map, void (*free_val)(void*))
{
@@ -1141,13 +1152,15 @@
tor_free(map);
}
-/* DOCDOC strmap_assert_ok */
+/** Fail with an assertion error if anything has gone wrong with the internal
+ * representation of <b>map</b>. */
void
strmap_assert_ok(const strmap_t *map)
{
tor_assert(!_strmap_impl_HT_REP_IS_BAD(&map->head));
}
-/* DOCDOC digestmap_assert_ok */
+/** Fail with an assertion error if anything has gone wrong with the internal
+ * representation of <b>map</b>. */
void
digestmap_assert_ok(const digestmap_t *map)
{
@@ -1161,7 +1174,7 @@
return HT_EMPTY(&map->head);
}
-/* DOCDOC digestmap_isempty */
+/** Return true iff <b>map</b> has no entries. */
int
digestmap_isempty(const digestmap_t *map)
{
@@ -1175,7 +1188,7 @@
return HT_SIZE(&map->head);
}
-/* DOCDOC digestmap_size */
+/** Return the number of items in <b>map</b>. */
int
digestmap_size(const digestmap_t *map)
{
Modified: tor/trunk/src/common/crypto.c
===================================================================
--- tor/trunk/src/common/crypto.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/crypto.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -2274,12 +2274,13 @@
tor_mutex_release(_openssl_mutexes[n]);
}
-/* DOCDOC CRYPTO_dynlock_value */
+/** OpenSSL helper type: wraps a Tor mutex so that openssl can */
struct CRYPTO_dynlock_value {
tor_mutex_t *lock;
};
-/* DOCDOC _openssl_dynlock_create_cb */
+/** Openssl callback function to allocate a lock: see CRYPTO_set_dynlock_*
+ * documentation in OpenSSL's docs for more info. */
static struct CRYPTO_dynlock_value *
_openssl_dynlock_create_cb(const char *file, int line)
{
@@ -2291,7 +2292,8 @@
return v;
}
-/* DOCDOC _openssl_dynlock_lock_cb */
+/** Openssl callback function to acquire or release a lock: see
+ * CRYPTO_set_dynlock_* documentation in OpenSSL's docs for more info. */
static void
_openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v,
const char *file, int line)
@@ -2304,7 +2306,8 @@
tor_mutex_release(v->lock);
}
-/* DOCDOC _openssl_dynlock_destroy_cb */
+/** Openssl callback function to free a lock: see CRYPTO_set_dynlock_*
+ * documentation in OpenSSL's docs for more info. */
static void
_openssl_dynlock_destroy_cb(struct CRYPTO_dynlock_value *v,
const char *file, int line)
Modified: tor/trunk/src/common/crypto.h
===================================================================
--- tor/trunk/src/common/crypto.h 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/crypto.h 2008-12-22 17:53:04 UTC (rev 17734)
@@ -51,13 +51,9 @@
/** Length of hex encoding of SHA1 digest, not including final NUL. */
#define HEX_DIGEST_LEN 40
-/* DOCDOC crypto_pk_env_t */
typedef struct crypto_pk_env_t crypto_pk_env_t;
-/* DOCDOC crypto_cipher_env_t */
typedef struct crypto_cipher_env_t crypto_cipher_env_t;
-/* DOCDOC crypto_digest_env_t */
typedef struct crypto_digest_env_t crypto_digest_env_t;
-/* DOCDOC crypto_dh_env_t */
typedef struct crypto_dh_env_t crypto_dh_env_t;
/* global state */
Modified: tor/trunk/src/common/log.c
===================================================================
--- tor/trunk/src/common/log.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/log.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -766,7 +766,8 @@
return 0;
}
#if 0
-/** DOCDOC */
+/** Translate a bitmask of log domains to a string, or NULL if the bitmask
+ * is undecodable. */
static const char *
domain_to_string(log_domain_mask_t domain)
{
Modified: tor/trunk/src/common/memarea.c
===================================================================
--- tor/trunk/src/common/memarea.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/memarea.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -85,7 +85,8 @@
}
}
-/* DOCDOC chunk_free */
+/** Release <b>chunk</b> from a memarea, either by adding it to the freelist
+ * or by freeing it if the freelist is already too big. */
static void
chunk_free(memarea_chunk_t *chunk)
{
Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/common/util.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -1341,14 +1341,16 @@
*/
static int ftime_skew = 0;
static int ftime_slop = 60;
-/* DOCDOC ftime_set_maximum_sloppiness */
+/** Set the largest amount of sloppiness we'll allow in fuzzy time
+ * comparisons. */
void
ftime_set_maximum_sloppiness(int seconds)
{
tor_assert(seconds >= 0);
ftime_slop = seconds;
}
-/* DOCDOC ftime_set_estimated_skew */
+/** Set the amount by which we believe our system clock to differ from
+ * real time. */
void
ftime_set_estimated_skew(int seconds)
{
@@ -1362,21 +1364,21 @@
ft_out->latest = now + ftime_skew + ftime_slop;
}
#endif
-/* DOCDOC ftime_maybe_after */
+/** Return true iff we think that <b>now</b> might be after <b>when</b>. */
int
ftime_maybe_after(time_t now, time_t when)
{
/* It may be after when iff the latest possible current time is after when */
return (now + ftime_skew + ftime_slop) >= when;
}
-/* DOCDOC ftime_maybe_before */
+/** Return true iff we think that <b>now</b> might be before <b>when</b>. */
int
ftime_maybe_before(time_t now, time_t when)
{
/* It may be before when iff the earliest possible current time is before */
return (now + ftime_skew - ftime_slop) < when;
}
-/* DOCDOC ftime_definitely_after */
+/** Return true if we think that <b>now</b> is definitely after <b>when</b>. */
int
ftime_definitely_after(time_t now, time_t when)
{
@@ -1384,7 +1386,7 @@
* after when. */
return (now + ftime_skew - ftime_slop) >= when;
}
-/* DOCDOC ftime_definitely_before */
+/** Return true if we think that <b>now</b> is definitely before <b>when</b>. */
int
ftime_definitely_before(time_t now, time_t when)
{
Modified: tor/trunk/src/or/buffers.c
===================================================================
--- tor/trunk/src/or/buffers.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/buffers.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -549,7 +549,8 @@
return chunk;
}
-/** DOCDOC */
+/** If we're using readv and writev, how many chunks are we willing to
+ * read/write at a time? */
#define N_IOV 3
/** Read up to <b>at_most</b> bytes from the socket <b>fd</b> into
Modified: tor/trunk/src/or/connection.c
===================================================================
--- tor/trunk/src/or/connection.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/connection.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -153,7 +153,8 @@
return buf;
}
-/* DOCDOC dir_connection_new */
+/** Allocate and return a new dir_connection_t, initialized as by
+ * connection_init(). */
dir_connection_t *
dir_connection_new(int socket_family)
{
@@ -161,7 +162,9 @@
connection_init(time(NULL), TO_CONN(dir_conn), CONN_TYPE_DIR, socket_family);
return dir_conn;
}
-/* DOCDOC or_connection_new */
+
+/** Allocate and return a new or_connection_t, initialized as by
+ * connection_init(). */
or_connection_t *
or_connection_new(int socket_family)
{
@@ -174,7 +177,9 @@
return or_conn;
}
-/* DOCDOC edge_connection_new */
+
+/** Allocate and return a new edge_connection_t, initialized as by
+ * connection_init(). */
edge_connection_t *
edge_connection_new(int type, int socket_family)
{
@@ -185,7 +190,9 @@
edge_conn->socks_request = tor_malloc_zero(sizeof(socks_request_t));
return edge_conn;
}
-/* DOCDOC control_connection_new */
+
+/** Allocate and return a new control_connection_t, initialized as by
+ * connection_init(). */
control_connection_t *
control_connection_new(int socket_family)
{
@@ -196,7 +203,9 @@
return control_conn;
}
-/* DOCDOC connection_new */
+/** Allocate, initialize, and return a new connection_t subtype of <b>type</b>
+ * to make or receive connections of address family <b>socket_family</b>. The
+ * type should be one of the CONN_TYPE_* constants. */
connection_t *
connection_new(int type, int socket_family)
{
@@ -811,7 +820,9 @@
};
#endif /* HAVE_SYS_UN_H */
-/* DOCDOC warn_too_many_conns */
+/** Warn that an accept or a connect has failed because we're running up
+ * against our ulimit. Rate-limit these warnings so that we don't spam
+ * the log. */
static void
warn_too_many_conns(void)
{
Modified: tor/trunk/src/or/control.c
===================================================================
--- tor/trunk/src/or/control.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/control.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -83,13 +83,25 @@
* of this so we can respond to getinfo status/bootstrap-phase queries. */
static char last_sent_bootstrap_message[BOOTSTRAP_MSG_LEN];
+/** Flag for event_format_t. Indicates that we should use the old
+ * name format of nickname|hexdigest
+ */
#define SHORT_NAMES 1
+/** Flag for event_format_t. Indicates that we should use the new
+ * name format of $hexdigest[=~]nickname
+ */
#define LONG_NAMES 2
#define ALL_NAMES (SHORT_NAMES|LONG_NAMES)
+/** Flag for event_format_t. Indicates that we should use the new event
+ * format where extra event fields are allowed using a NAME=VAL format. */
#define EXTENDED_FORMAT 4
+/** Flag for event_format_t. Indicates that we are using the old event format
+ * where extra fields aren't allowed. */
#define NONEXTENDED_FORMAT 8
#define ALL_FORMATS (EXTENDED_FORMAT|NONEXTENDED_FORMAT)
-/* DOCDOC event_format_t */
+
+/** Bit field of flags to select how to format a controller event. Recognized
+ * flags are SHORT_NAMES, LONG_NAMES, EXTENDED_FORMAT, NONEXTENDED_FORMAT. */
typedef int event_format_t;
static void connection_printf_to_buf(control_connection_t *conn,
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/directory.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -862,18 +862,17 @@
return strcmp(s1, s2);
}
+#define CONDITIONAL_CONSENSUS_FPR_LEN 3
+#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
+#error "conditional consensus fingerprint length is larger than digest length"
+#endif
+
/** Return the URL we should use for a consensus download.
*
* This url depends on whether or not the server we go to
* is sufficiently new to support conditional consensus downloading,
* i.e. GET .../consensus/<b>fpr</b>+<b>fpr</b>+<b>fpr</b>
*/
-#define CONDITIONAL_CONSENSUS_FPR_LEN 3
-#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
-#error "conditional consensus fingerprint length is larger than digest length"
-#endif
-
-/* DOCDOC directory_get_consensus_url */
static char *
directory_get_consensus_url(int supports_conditional_consensus)
{
@@ -2195,7 +2194,10 @@
* of request. Maps from request type to pointer to request_t. */
static strmap_t *request_map = NULL;
-/* DOCDOC note_client_request */
+/** Record that a client request of <b>purpose</b> was made, and that
+ * <b>bytes</b> bytes of possibly <b>compressed</b> data were sent/received.
+ * Used to keep track of how much we've up/downloaded in what kind of
+ * request. */
static void
note_client_request(int purpose, int compressed, size_t bytes)
{
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/dirserv.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -1587,7 +1587,8 @@
"v1 network status list", V1_AUTHORITY);
}
-/* DOCDOC */
+/** Return the latest downloaded consensus networkstatus in encoded, signed,
+ * optionally compressed format, suitable for sending to clients. */
cached_dir_t *
dirserv_get_consensus(void)
{
Modified: tor/trunk/src/or/dirvote.c
===================================================================
--- tor/trunk/src/or/dirvote.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/dirvote.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -219,7 +219,9 @@
return smartlist_get(vote->voters, 0);
}
-/* DOCDOC dir_src_ent_t */
+/** Temporary structure used in constructing a list of dir-source entries
+ * for a consensus. One of these is generated for every vote, and one more
+ * for every legacy key in each vote. */
typedef struct dir_src_ent_t {
networkstatus_t *v;
const char *digest;
@@ -236,7 +238,9 @@
get_voter(b)->identity_digest, DIGEST_LEN);
}
-/* DOCDOC _compare_dir_src_ents_by_authority_id */
+/** Helper: Compare the dir_src_ent_ts in *<b>_a</b> and *<b>_b</b> by
+ * their identity digests, and return -1, 0, or 1 depending on their
+ * ordering */
static int
_compare_dir_src_ents_by_authority_id(const void **_a, const void **_b)
{
Modified: tor/trunk/src/or/dns.c
===================================================================
--- tor/trunk/src/or/dns.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/dns.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -186,9 +186,10 @@
log(severity, LD_EXIT, "eventdns: %s", msg);
}
-/* DOCDOC randfn */
+/** Helper: passed to eventdns.c as a callback so it can generate random
+ * numbers for transaction IDs and 0x20-hack coding. */
static void
-randfn(char *b, size_t n)
+_dns_randfn(char *b, size_t n)
{
crypto_rand(b,n);
}
@@ -198,7 +199,7 @@
dns_init(void)
{
init_cache_map();
- evdns_set_random_bytes_fn(randfn);
+ evdns_set_random_bytes_fn(_dns_randfn);
if (get_options()->ServerDNSRandomizeCase)
evdns_set_option("randomize-case", "1", DNS_OPTIONS_ALL);
else
Modified: tor/trunk/src/or/geoip.c
===================================================================
--- tor/trunk/src/or/geoip.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/geoip.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -438,7 +438,8 @@
* are willing to talk about it? */
#define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
-/* DOCDOC round_to_next_multiple_of */
+/** Return the lowest x such that x is at least <b>number</b>, and x modulo
+ * <b>divisor</b> == 0. */
static INLINE unsigned
round_to_next_multiple_of(unsigned number, unsigned divisor)
{
@@ -589,7 +590,7 @@
return result;
}
-/* DOCDOC dump_geoip_stats */
+/** Store all our geoip statistics into $DATADIR/geoip-stats. */
void
dump_geoip_stats(void)
{
Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/main.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -1902,14 +1902,14 @@
}
}
-/* DOCDOC have_lockfile */
+/** Return true iff we've successfully acquired the lock file. */
int
have_lockfile(void)
{
return lockfile != NULL;
}
-/* DOCDOC release_lockfile */
+/** If we have successfully acquired the lock file, release it. */
void
release_lockfile(void)
{
Modified: tor/trunk/src/or/policies.c
===================================================================
--- tor/trunk/src/or/policies.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/policies.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -235,7 +235,10 @@
}
}
-/* DOCDOC XXXX deprecate when possible. */
+/** Return true iff <b> policy</b> (possibly NULL) will allow a connection to
+ * <b>addr</b>:<b>port</b>. <b>addr</b> is an IPv4 address given in host
+ * order. */
+/* XXXX deprecate when possible. */
static int
addr_policy_permits_address(uint32_t addr, uint16_t port,
smartlist_t *policy)
@@ -254,7 +257,8 @@
reachable_or_addr_policy);
}
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make an OR connection to
+ * <b>ri</b>. */
int
fascist_firewall_allows_or(routerinfo_t *ri)
{
@@ -552,7 +556,8 @@
return found->policy;
}
-/** DOCDOC */
+/** As compare_to_addr_to_addr_policy, but instead of a tor_addr_t, takes
+ * in host order. */
addr_policy_result_t
compare_addr_to_addr_policy(uint32_t addr, uint16_t port, smartlist_t *policy)
{
Modified: tor/trunk/src/or/relay.c
===================================================================
--- tor/trunk/src/or/relay.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/relay.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -1470,7 +1470,9 @@
++total_cells_allocated;
return mp_pool_get(cell_pool);
}
-/* DOCDOC dump_cell_pool_usage */
+
+/** Log current statistics for cell pool allocation at log level
+ * <b>severity</b>. */
void
dump_cell_pool_usage(int severity)
{
Modified: tor/trunk/src/or/router.c
===================================================================
--- tor/trunk/src/or/router.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/router.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -149,14 +149,17 @@
return authority_signing_key;
}
-/* DOCDOC get_my_v3_legacy_cert */
+/** If we're an authority, and we're using a legacy authority identity key for
+ * emergency migration purposes, return the certificate associated with that
+ * key. */
authority_cert_t *
get_my_v3_legacy_cert(void)
{
return legacy_key_certificate;
}
-/* DOCDOC get_my_v3_legacy_signing_key */
+/** If we're an authority, and we're using a legacy authority identity key for
+ * emergency migration purposes, return that key. */
crypto_pk_env_t *
get_my_v3_legacy_signing_key(void)
{
@@ -285,10 +288,14 @@
return NULL;
}
-/* DOCDOC load_authority_keyset */
+/** Try to load the vote-signing private key and certificate for being a v3
+ * directory authority, and make sure they match. If <b>legacy</b>, load a
+ * legacy key/cert set for emergency key migration; otherwise load the regular
+ * key/cert set. On success, store them into *<b>key_out</b> and
+ * *<b>cert_out</b> respectively, and return 0. On failrue, return -1. */
static int
load_authority_keyset(int legacy, crypto_pk_env_t **key_out,
- authority_cert_t **cert_out)
+ authority_cert_t **cert_out)
{
int r = -1;
char *fname = NULL, *cert = NULL;
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/routerlist.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -549,7 +549,8 @@
return store->journal_len > (1<<15);
}
-/* DOCDOC desc_get_store */
+/** Return the desc_store_t in <b>rl</b> that should be used to store
+ * <b>sd</b>. */
static INLINE desc_store_t *
desc_get_store(routerlist_t *rl, signed_descriptor_t *sd)
{
@@ -2466,7 +2467,10 @@
#endif
}
-/* DOCDOC _routerlist_find_elt */
+/** Debugging helper: If <b>idx</b> is nonnegative, assert that <b>ri</b> is
+ * in <b>sl</b> at position <b>idx</b>. Otherwise, search <b>sl</b> for
+ * <b>ri</b>. Return the index of <b>ri</b> in <b>sl</b>, or -1 if <b>ri</b>
+ * is not in <b>sl</b>. */
static INLINE int
_routerlist_find_elt(smartlist_t *sl, void *ri, int idx)
{
Modified: tor/trunk/src/or/routerparse.c
===================================================================
--- tor/trunk/src/or/routerparse.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/routerparse.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -2847,7 +2847,11 @@
goto done_tokenizing; \
STMT_END
-/* DOCDOC token_check_object */
+/** Helper: make sure that the token <b>tok</b> with keyword <b>kwd</b> obeys
+ * the object syntax of <b>o_syn</b>. Allocate all storage in <b>area</b>.
+ * Return <b>tok</b> on success, or a new _ERR token if the token didn't
+ * conform to the syntax we wanted.
+ **/
static INLINE directory_token_t *
token_check_object(memarea_t *area, const char *kwd,
directory_token_t *tok, obj_syntax o_syn)
@@ -2855,6 +2859,7 @@
char ebuf[128];
switch (o_syn) {
case NO_OBJ:
+ /* No object is allowed for this token. */
if (tok->object_body) {
tor_snprintf(ebuf, sizeof(ebuf), "Unexpected object for %s", kwd);
RET_ERR(ebuf);
@@ -2865,20 +2870,21 @@
}
break;
case NEED_OBJ:
+ /* There must be a (non-key) object. */
if (!tok->object_body) {
tor_snprintf(ebuf, sizeof(ebuf), "Missing object for %s", kwd);
RET_ERR(ebuf);
}
break;
- case NEED_KEY_1024:
- case NEED_SKEY_1024:
+ case NEED_KEY_1024: /* There must be a 1024-bit public key. */
+ case NEED_SKEY_1024: /* There must be a 1024-bit private key. */
if (tok->key && crypto_pk_keysize(tok->key) != PK_BYTES) {
tor_snprintf(ebuf, sizeof(ebuf), "Wrong size on key for %s: %d bits",
kwd, (int)crypto_pk_keysize(tok->key));
RET_ERR(ebuf);
}
/* fall through */
- case NEED_KEY:
+ case NEED_KEY: /* There must be some kind of key. */
if (!tok->key) {
tor_snprintf(ebuf, sizeof(ebuf), "Missing public key for %s", kwd);
}
@@ -2897,6 +2903,7 @@
}
break;
case OBJ_OK:
+ /* Anything goes with this token. */
break;
}
Modified: tor/trunk/src/or/test.c
===================================================================
--- tor/trunk/src/or/test.c 2008-12-22 16:57:59 UTC (rev 17733)
+++ tor/trunk/src/or/test.c 2008-12-22 17:53:04 UTC (rev 17734)
@@ -54,7 +54,9 @@
static char temp_dir[256];
-/* DOCDOC setup_directory */
+/** Select and create the temporary directory we'll use to run our unit tests.
+ * Store it in <b>temp_dir</b>. Exit immediately if we can't create it.
+ * idempotent. */
static void
setup_directory(void)
{
@@ -79,7 +81,7 @@
is_setup = 1;
}
-/* DOCDOC get_fname */
+/** Return a filename relative to our testing temporary directory */
static const char *
get_fname(const char *name)
{
@@ -89,7 +91,8 @@
return buf;
}
-/* DOCDOC remove_directory */
+/** Remove all files stored under the temporary directory, and the directory
+ * itself. */
static void
remove_directory(void)
{
@@ -113,12 +116,17 @@
#undef CACHE_GENERATED_KEYS
static crypto_pk_env_t *pregen_keys[5] = {NULL, NULL, NULL, NULL, NULL};
-/* DOCDOC pk_generate */
+#define N_PREGEN_KEYS ((int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])))
+
+/** Generate and return a new keypair for use in unit tests. If we're using
+ * the key cache optimization, we might reuse keys: we only guarantee that
+ * keys made with distinct values for <b>idx</b> are different. The value of
+ * <b>idx</b> must be at least 0, and less than N_PREGEN_KEYS. */
static crypto_pk_env_t *
pk_generate(int idx)
{
#ifdef CACHE_GENERATED_KEYS
- tor_assert(idx < (int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])));
+ tor_assert(idx < N_PREGEN_KEYS);
if (! pregen_keys[idx]) {
pregen_keys[idx] = crypto_new_pk_env();
tor_assert(!crypto_pk_generate_key(pregen_keys[idx]));
@@ -133,12 +141,12 @@
#endif
}
-/* DOCDOC free_pregenerated_keys */
+/** Free all storage used for the cached key optimization. */
static void
free_pregenerated_keys(void)
{
unsigned idx;
- for (idx = 0; idx < sizeof(pregen_keys)/sizeof(pregen_keys[0]); ++idx) {
+ for (idx = 0; idx < N_PREGEN_KEYS; ++idx) {
if (pregen_keys[idx]) {
crypto_free_pk_env(pregen_keys[idx]);
pregen_keys[idx] = NULL;
@@ -146,7 +154,7 @@
}
}
-/* DOCDOC test_buffers */
+/** Run unit tests for buffers.c */
static void
test_buffers(void)
{
@@ -389,7 +397,7 @@
buf_free(buf2);
}
-/* DOCDOC test_crypto_dh */
+/** Run unit tests for Diffie-Hellman functionality. */
static void
test_crypto_dh(void)
{
@@ -431,7 +439,8 @@
crypto_dh_free(dh2);
}
-/* DOCDOC test_crypto_rng */
+/** Run unit tests for our random number generation function and its wrappers.
+ */
static void
test_crypto_rng(void)
{
@@ -469,7 +478,7 @@
;
}
-/* DOCDOC test_crypto_aes */
+/** Run unit tests for our AES functionality */
static void
test_crypto_aes(void)
{
@@ -599,7 +608,7 @@
tor_free(data3);
}
-/* DOCDOC test_crypto_sha */
+/** Run unit tests for our SHA-1 functionality */
static void
test_crypto_sha(void)
{
@@ -668,7 +677,7 @@
crypto_free_digest_env(d2);
}
-/* DOCDOC test_crypto_pk */
+/** Run unit tests for our public key crypto functions */
static void
test_crypto_pk(void)
{
@@ -778,7 +787,7 @@
tor_free(encoded);
}
-/* DOCDOC test_crypto */
+/** Run unit tests for misc crypto functionality. */
static void
test_crypto(void)
{
@@ -887,7 +896,7 @@
tor_free(data3);
}
-/* DOCDOC test_crypto_s2k */
+/** Run unit tests for our secret-to-key passphrase hashing functionality. */
static void
test_crypto_s2k(void)
{
@@ -920,7 +929,8 @@
tor_free(buf3);
}
-/* DOCDOC _compare_strs */
+/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
+ * *<b>b</b>. */
static int
_compare_strs(const void **a, const void **b)
{
@@ -928,7 +938,8 @@
return strcmp(s1, s2);
}
-/* DOCDOC _compare_without_first_ch */
+/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
+ * *<b>b</b>, excluding a's first character, and ignoring case. */
static int
_compare_without_first_ch(const void *a, const void **b)
{
@@ -936,7 +947,7 @@
return strcasecmp(s1+1, s2);
}
-/* DOCDOC test_util */
+/** Test basic utility functionality. */
static void
test_util(void)
{
@@ -1429,7 +1440,7 @@
test_eq(port2, pt2); \
STMT_END
-/* DOCDOC test_util_ip6_helpers */
+/** Run unit tests for IPv6 encoding/decoding/manipulation functions. */
static void
test_util_ip6_helpers(void)
{
@@ -1755,7 +1766,7 @@
;
}
-/* DOCDOC test_util_smartlist_basic */
+/** Run unit tests for basic dynamic-sized array functionality. */
static void
test_util_smartlist_basic(void)
{
@@ -1794,7 +1805,7 @@
smartlist_free(sl);
}
-/* DOCDOC test_util_smartlist_strings */
+/** Run unit tests for smartlist-of-strings functionality. */
static void
test_util_smartlist_strings(void)
{
@@ -2024,7 +2035,7 @@
tor_free(cp_alloc);
}
-/* DOCDOC test_util_smartlist_overlap */
+/** Run unit tests for smartlist set manipulation functions. */
static void
test_util_smartlist_overlap(void)
{
@@ -2077,7 +2088,7 @@
smartlist_free(sl);
}
-/* DOCDOC test_util_smartlist_digests */
+/** Run unit tests for smartlist-of-digests functions. */
static void
test_util_smartlist_digests(void)
{
@@ -2110,7 +2121,7 @@
smartlist_free(sl);
}
-/* DOCDOC test_util_smartlist_join */
+/** Run unit tests for concatenate-a-smartlist-of-strings functions. */
static void
test_util_smartlist_join(void)
{
@@ -2162,7 +2173,7 @@
tor_free(joined);
}
-/* DOCDOC test_util_bitarray */
+/** Run unit tests for bitarray code */
static void
test_util_bitarray(void)
{
@@ -2204,7 +2215,8 @@
bitarray_free(ba);
}
-/* DOCDOC test_util_digestset */
+/** Run unit tests for digest set code (implemented as a hashtable or as a
+ * bloom filter) */
static void
test_util_digestset(void)
{
@@ -2253,18 +2265,18 @@
static char *_thread1_name = NULL;
static char *_thread2_name = NULL;
-/* DOCDOC _thread_test_func */
static void _thread_test_func(void* _s) ATTR_NORETURN;
static int t1_count = 0;
static int t2_count = 0;
+/** Helper function for threading unit tests: This function runs in a
+ * subthread. It grabs its own mutex (start1 or start2) to make sure that it
+ * should start, then it repeatedly alters _test_thread_strmap protected by
+ * _thread_test_mutex. */
static void
_thread_test_func(void* _s)
{
- /* This function runs in a subthread. It grabs its own mutex (start1 or
- * start2) to make sure that it should start, then it repeatedly alters
- * _test_thread_strmap protected by _thread_test_mutex. */
char *s = _s;
int i, *count;
tor_mutex_t *m;
@@ -2299,7 +2311,7 @@
spawn_exit();
}
-/* DOCDOC test_util_threads */
+/** Run unit tests for threading logic. */
static void
test_util_threads(void)
{
@@ -2371,14 +2383,14 @@
tor_mutex_free(_thread_test_start2);
}
-/* DOCDOC _compare_strings_for_pqueue */
+/** Helper: return a tristate based on comparing two strings. */
static int
_compare_strings_for_pqueue(const void *s1, const void *s2)
{
return strcmp((const char*)s1, (const char*)s2);
}
-/* DOCDOC test_util_pqueue */
+/** Run unit tests for heap-based priority queue functions. */
static void
test_util_pqueue(void)
{
@@ -2436,7 +2448,7 @@
smartlist_free(sl);
}
-/* DOCDOC test_util_gzip */
+/** Run unit tests for compression functions */
static void
test_util_gzip(void)
{
@@ -2543,7 +2555,7 @@
tor_free(buf1);
}
-/* DOCDOC test_util_strmap */
+/** Run unit tests for string-to-void* map functions */
static void
test_util_strmap(void)
{
@@ -2634,7 +2646,7 @@
tor_free(visited);
}
-/* DOCDOC test_util_mmap */
+/** Run unit tests for mmap() wrapper functionality. */
static void
test_util_mmap(void)
{
@@ -2711,7 +2723,7 @@
tor_munmap_file(mapping);
}
-/* DOCDOC test_util_control_formats */
+/** Run unit tests for escaping/unescaping data for use by controllers. */
static void
test_util_control_formats(void)
{
@@ -2729,7 +2741,7 @@
tor_free(out);
}
-/* DOCDOC test_onion_handshake */
+/** Run unit tests for the onion handshake code. */
static void
test_onion_handshake(void)
{
@@ -2778,7 +2790,7 @@
extern smartlist_t *fingerprint_list;
-/* DOCDOC test_dir_format */
+/** Run unit tests for router descriptor generation logic. */
static void
test_dir_format(void)
{
@@ -3099,7 +3111,7 @@
tor_free(dir2); /* And more !*/
}
-/* DOCDOC test_dirutil */
+/** Run unit tests for misc directory functions. */
static void
test_dirutil(void)
{
@@ -3135,7 +3147,9 @@
extern const char AUTHORITY_CERT_3[];
extern const char AUTHORITY_SIGNKEY_3[];
-/* DOCDOC test_same_voter */
+/** Helper: Test that two networkstatus_voter_info_t do in fact represent the
+ * same voting authority, and that they do in fact have all the same
+ * information. */
static void
test_same_voter(networkstatus_voter_info_t *v1,
networkstatus_voter_info_t *v2)
@@ -3152,7 +3166,7 @@
;
}
-/* DOCDOC test_util_order_functions */
+/** Run unit tests for getting the median of a list. */
static void
test_util_order_functions(void)
{
@@ -3182,7 +3196,8 @@
;
}
-/* DOCDOC generate_ri_from_rs */
+/** Helper: Make a new routerinfo containing the right information for a
+ * given vote_routerstatus_t. */
static routerinfo_t *
generate_ri_from_rs(const vote_routerstatus_t *vrs)
{
@@ -3205,7 +3220,8 @@
return r;
}
-/* DOCDOC test_v3_networkstatus */
+/** Run unit tests for generating and parsing V3 consensus networkstatus
+ * documents. */
static void
test_v3_networkstatus(void)
{
@@ -3704,7 +3720,9 @@
ns_detached_signatures_free(dsig2);
}
-/* DOCDOC test_policy_summary_helper */
+/** Helper: Parse the exit policy string in <b>policy_str</b>, and make sure
+ * that policies_summarize() produces the string <b>expected_summary</b> from
+ * it. */
static void
test_policy_summary_helper(const char *policy_str,
const char *expected_summary)
@@ -3731,7 +3749,7 @@
addr_policy_list_free(policy);
}
-/* DOCDOC test_policies */
+/** Run unit tests for generating summary lines of exit policies */
static void
test_policies(void)
{
@@ -3890,7 +3908,7 @@
}
}
-/* DOCDOC test_rend_fns */
+/** Run unit tests for basic rendezvous functions. */
static void
test_rend_fns(void)
{
@@ -3956,7 +3974,7 @@
tor_free(encoded);
}
-/* DOCDOC bench_aes */
+/** Run AES performance benchmarks. */
static void
bench_aes(void)
{
@@ -3988,7 +4006,7 @@
crypto_free_cipher_env(c);
}
-/* DOCDOC bench_dmap */
+/** Run digestmap_t performance benchmarks. */
static void
bench_dmap(void)
{
@@ -4052,7 +4070,7 @@
smartlist_free(sl2);
}
-/* DOCDOC test_util_mempool */
+/** Run unittests for memory pool allocator */
static void
test_util_mempool(void)
{
@@ -4110,7 +4128,7 @@
mp_pool_destroy(pool);
}
-/* DOCDOC test_util_memarea */
+/** Run unittests for memory area allocator */
static void
test_util_memarea(void)
{
@@ -4206,7 +4224,8 @@
tor_free(malloced_ptr);
}
-/* DOCDOC test_util_datadir */
+/** Run unit tests for utility functions to get file names relative to
+ * the data directory. */
static void
test_util_datadir(void)
{
@@ -4239,8 +4258,7 @@
tor_free(f);
}
-/* Test AES-CTR encryption and decryption with IV. */
-/* DOCDOC test_crypto_aes_iv */
+/** Test AES-CTR encryption and decryption with IV. */
static void
test_crypto_aes_iv(void)
{
@@ -4376,8 +4394,7 @@
crypto_free_cipher_env(cipher);
}
-/* Test base32 decoding. */
-/* DOCDOC test_crypto_base32_decode */
+/** Test base32 decoding. */
static void
test_crypto_base32_decode(void)
{
@@ -4412,8 +4429,7 @@
;
}
-/* Test encoding and parsing of v2 rendezvous service descriptors. */
-/* DOCDOC test_rend_fns_v2 */
+/** Test encoding and parsing of v2 rendezvous service descriptors. */
static void
test_rend_fns_v2(void)
{
@@ -4514,7 +4530,7 @@
tor_free(intro_points_encrypted);
}
-/* DOCDOC test_geoip */
+/** Run unit tests for GeoIP code. */
static void
test_geoip(void)
{
@@ -4580,6 +4596,7 @@
void (*test_fn)(void);
int is_subent;
int selected;
+ int is_default;
} test_array[] = {
ENT(buffers),
ENT(crypto),
@@ -4618,11 +4635,12 @@
ENT(rend_fns),
SUBENT(rend_fns, v2),
ENT(geoip),
- { NULL, NULL, 0, 0 },
+ { NULL, NULL, 0, 0, 0 },
};
static void syntax(void) ATTR_NORETURN;
-/* DOCDOC syntax */
+
+/** Print a syntax usage message, and exit.*/
static void
syntax(void)
{
@@ -4638,7 +4656,8 @@
exit(0);
}
-/* DOCDOC main */
+/** Main entry point for unit test code: parse the command line, and run
+ * some unit tests. */
int
main(int c, char**v)
{
More information about the tor-commits
mailing list