Commit 50f22e85 authored by Roger Dingledine's avatar Roger Dingledine
Browse files

doc pedant


svn:r9634
parent f599adf4
......@@ -990,8 +990,8 @@ typedef struct tor_pthread_data_t {
void (*func)(void *);
void *data;
} tor_pthread_data_t;
/** Given a tor_pthread_data_t <b>d</b>, call d-&gt;func(d-&gt;data);, and
* free d. Used to make sure we can call functions the way pthread
/** Given a tor_pthread_data_t <b>_data</b>, call _data-&gt;func(d-&gt;data);,
* and free _data. Used to make sure we can call functions the way pthread
* expects. */
static void *
tor_pthread_helper_fn(void *_data)
......
......@@ -299,8 +299,8 @@ detect_compression_method(const char *in, size_t in_len)
}
}
/** Internal state for a incremental zlib compression/decompression. The body
* of this struct is not exposed. */
/** Internal state for an incremental zlib compression/decompression. The
* body of this struct is not exposed. */
struct tor_zlib_state_t {
struct z_stream_s stream;
int compress;
......@@ -308,7 +308,7 @@ struct tor_zlib_state_t {
/** Construct and return a tor_zlib_state_t object using <b>method</b>. If
* <b>compress</b>, it's for compression; otherwise it's for
* decompression. */
* decompression. */
tor_zlib_state_t *
tor_zlib_new(int compress, compress_method_t method)
{
......
......@@ -862,7 +862,7 @@ tv_addms(struct timeval *a, long ms)
a->tv_usec %= 1000000;
}
/** Yield true iff <b>y</b> is a leap-year */
/** Yield true iff <b>y</b> is a leap-year. */
#define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
/** Helper: Return the number of leap-days between Jan 1, y1 and Jan 1, y2. */
static int
......@@ -1957,9 +1957,9 @@ get_interface_address(int severity, uint32_t *addr)
#ifndef MS_WINDOWS
/* Based on code contributed by christian grothoff */
/** True iff we've called start_daemon. */
/** True iff we've called start_daemon(). */
static int start_daemon_called = 0;
/** True iff we've called finish_daemon. */
/** True iff we've called finish_daemon(). */
static int finish_daemon_called = 0;
/** Socketpair used to communicate between parent and child process while
* daemonizing. */
......
......@@ -24,20 +24,20 @@ const char buffers_c_id[] =
* end/before the start of the buffer.
*/
#ifdef SENTINELS
/* 4-byte value to write at the start of each buffer memory region */
/** 4-byte value to write at the start of each buffer memory region. */
#define START_MAGIC 0x70370370u
/* 4-byte value to write at the end of each buffer memory region */
/** 4-byte value to write at the end of each buffer memory region. */
#define END_MAGIC 0xA0B0C0D0u
/* Given buf-&gt;mem, yield a pointer to the raw memory region (for free(),
* realloc(), and so on) */
/** Given buf-&gt;mem, yield a pointer to the raw memory region (for free(),
* realloc(), and so on). */
#define RAW_MEM(m) ((void*)(((char*)m)-4))
/* Given a pointer to the raw memory region (from malloc() or realloc()),
/** Given a pointer to the raw memory region (from malloc() or realloc()),
* yield the correct value for buf-&gt;mem (just past the first sentinel). */
#define GUARDED_MEM(m) ((void*)(((char*)m)+4))
/* How much memory do we need to allocate for a buffer to hold <b>ln</b> bytes
/** How much memory do we need to allocate for a buffer to hold <b>ln</b> bytes
* of data? */
#define ALLOC_LEN(ln) ((ln)+8)
/* Initialize the sentinel values on <b>m</b> (a value of buf-&gt;mem), which
/** Initialize the sentinel values on <b>m</b> (a value of buf-&gt;mem), which
* has <b>ln</b> useful bytes. */
#define SET_GUARDS(m, ln) \
do { set_uint32((m)-4,START_MAGIC); set_uint32((m)+ln,END_MAGIC); } while (0)
......@@ -64,10 +64,10 @@ const char buffers_c_id[] =
/** A resizeable buffer, optimized for reading and writing. */
struct buf_t {
uint32_t magic; /**< Magic cookie for debugging: Must be set to
* BUFFER_MAGIC */
char *mem; /**< Storage for data in the buffer */
* BUFFER_MAGIC. */
char *mem; /**< Storage for data in the buffer. */
char *cur; /**< The first byte used for storing data in the buffer. */
size_t highwater; /**< Largest observed datalen since last buf_shrink */
size_t highwater; /**< Largest observed datalen since last buf_shrink. */
size_t len; /**< Maximum amount of data that <b>mem</b> can hold. */
size_t memsize; /**< How many bytes did we actually allocate? Can be less
* than 'len' if we shortened 'len' by a few bytes to make
......
......@@ -1112,7 +1112,7 @@ router_handles_some_port(routerinfo_t *router, smartlist_t *needed_ports)
return 0;
}
/** Return true iff <b>conn</b> is waiting for a general circuit to be
/** Return true iff <b>conn</b> needs another general circuit to be
* built. */
static int
ap_stream_wants_exit_attention(connection_t *conn)
......
......@@ -565,10 +565,10 @@ circuit_expire_old_circuits(time_t now)
}
}
/** Number of circuits to open at once when testing our bandwidth. */
/** Number of testing circuits we want open before testing our bandwidth. */
#define NUM_PARALLEL_TESTING_CIRCS 4
/** True iff we've ever opened enough testing circuits to test our
/** True iff we've ever had enough testing circuits open to test our
* bandwidth. */
static int have_performed_bandwidth_test = 0;
......
......@@ -505,7 +505,7 @@ static config_var_description_t state_description[] = {
};
/** Type of a callback to validate whether a given configuration is
* well-formed and consistant. See options_trial_assign for documentation
* well-formed and consistent. See options_trial_assign() for documentation
* of arguments. */
typedef int (*validate_fn_t)(void*,void*,int,char**);
......@@ -516,9 +516,9 @@ typedef struct {
size_t size; /**< Size of the struct that everything gets parsed into. */
uint32_t magic; /**< Required 'magic value' to make sure we have a struct
* of the right type. */
off_t magic_offset; /**< Offset of the magic value within the struct */
off_t magic_offset; /**< Offset of the magic value within the struct. */
config_abbrev_t *abbrevs; /**< List of abbreviations that we expand when
* parsing this format */
* parsing this format. */
config_var_t *vars; /**< List of variables we recognize, their default
* values, and where we stick them in the structure. */
validate_fn_t validate_fn; /**< Function to validate config. */
......@@ -3801,7 +3801,7 @@ init_libevent(void)
}
#if defined(HAVE_EVENT_GET_VERSION) && defined(HAVE_EVENT_GET_METHOD)
/** Table mapping return value of event_get_version() to le_version_t */
/** Table mapping return value of event_get_version() to le_version_t. */
static const struct {
const char *name; le_version_t version;
} le_version_table[] = {
......@@ -3837,7 +3837,7 @@ decode_libevent_version(void)
/**
* Compare the given libevent method and version to a list of versions
* which are known not to work. Warn the user as appropriate.
a */
*/
static void
check_libevent_version(const char *m, int server)
{
......
......@@ -15,7 +15,7 @@ const char control_c_id[] =
* finished authentication and is accepting commands. */
#define STATE_IS_OPEN(s) ((s) == CONTROL_CONN_STATE_OPEN_V0 || \
(s) == CONTROL_CONN_STATE_OPEN_V1)
/** Yield trie iff <b>s</b> is the state of a control_connection_t that is
/** Yield true iff <b>s</b> is the state of a control_connection_t that is
* speaking the V0 protocol.
*/
#define STATE_IS_V0(s) ((s) == CONTROL_CONN_STATE_NEEDAUTH_V0 || \
......@@ -24,7 +24,6 @@ const char control_c_id[] =
/*
* See control-spec.txt and control-spec-v0.txt for full details on
* protocol(s).
*
*/
/* Recognized version 0 message type codes; do not add new codes to this list.
......@@ -725,7 +724,7 @@ send_control1_event_string(uint16_t event, event_format_t which,
* sent only to controllers that have enabled extended events.
*
* Currently the length of the message is limited to 1024 (including the
* ending \n\r\0. */
* ending \n\r\0). */
static void
send_control1_event_impl(uint16_t event, event_format_t which, int extended,
const char *format, va_list ap)
......@@ -1535,7 +1534,7 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
return 0;
}
/** Implementatino helper for GETINFO: knows the answers for questions about
/** Implementation helper for GETINFO: knows the answers for questions about
* directory information. */
static int
getinfo_helper_dir(control_connection_t *control_conn,
......@@ -1801,7 +1800,7 @@ typedef int (*getinfo_helper_t)(control_connection_t *,
/** A single item for the GETINFO question-to-answer-function table. */
typedef struct getinfo_item_t {
const char *varname; /**< The value (or prefix) of the question */
const char *varname; /**< The value (or prefix) of the question. */
getinfo_helper_t fn; /**< The function that knows the answer: NULL if
* this entry is documentation-only. */
const char *desc; /**< Description of the variable. */
......@@ -3337,9 +3336,9 @@ control_event_stream_status(edge_connection_t *conn, stream_status_event_t tp,
return 0;
}
/** Figure out best name for the target router of an OR connection, and write
* it into the <b>len</b>-character buffer <b>name</b>. Use verbose names if
* <b>long_names</b> is set. */
/** Figure out the best name for the target router of an OR connection
* <b>conn</b>, and write it into the <b>len</b>-character buffer
* <b>name</b>. Use verbose names if <b>long_names</b> is set. */
static void
orconn_target_get_name(int long_names,
char *name, size_t len, or_connection_t *conn)
......@@ -3366,7 +3365,7 @@ orconn_target_get_name(int long_names,
}
}
/** Convert a TOR_TLS error code into an END_OR_CONN_* reason. */
/** Convert a TOR_TLS_* error code into an END_OR_CONN_* reason. */
int
control_tls_error_to_reason(int e)
{
......@@ -3428,7 +3427,7 @@ or_conn_end_reason_to_string(int r)
*/
int
control_event_or_conn_status(or_connection_t *conn, or_conn_status_event_t tp,
int reason)
int reason)
{
char buf[HEX_DIGEST_LEN+3]; /* status, dollar, identity, NUL */
size_t len;
......
......@@ -62,11 +62,11 @@ typedef struct router_status_t {
/** List of nickname-\>identity fingerprint mappings for all the routers
* 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 router_status_t. */
strmap_t *fp_by_name; /**< Map from lc nickname to fingerprint. */
digestmap_t *status_by_digest; /**< Map from digest to router_status_t. */
} authdir_config_t;
/** Should be static; exposed for testing */
/** Should be static; exposed for testing. */
authdir_config_t *fingerprint_list = NULL;
/** Allocate and return a new, empty, authdir_config_t. */
......
......@@ -973,7 +973,7 @@ run_scheduled_events(time_t now)
}
}
/** Libevent timer: used to invoke second_elapsed_callback once per second. */
/** Libevent timer: used to invoke second_elapsed_callback() once per second. */
static struct event *timeout_event = NULL;
/** Number of libevent errors in the last second: we die if we get too many. */
static int n_libevent_errors = 0;
......
......@@ -25,7 +25,7 @@ typedef struct onion_queue_t {
/** 5 seconds on the onion queue til we just send back a destroy */
#define ONIONQUEUE_WAIT_CUTOFF 5
/** First and last elements in the linked list of of circuits waiting for CPU
/** First and last elements in the linked list of circuits waiting for CPU
* workers, or NULL if the list is empty. */
static onion_queue_t *ol_list=NULL;
static onion_queue_t *ol_tail=NULL;
......
......@@ -160,17 +160,17 @@
/** Length of a router identity encoded as a hexadecimal digest, plus
* possible dollar sign. */
#define MAX_HEX_NICKNAME_LEN (HEX_DIGEST_LEN+1)
/** Maximum length of verbose router identifier (Dollar sign, hex ID digest,
* equal or tilde, nickname) */
/** Maximum length of verbose router identifier: dollar sign, hex ID digest,
* equal sign or tilde, nickname. */
#define MAX_VERBOSE_NICKNAME_LEN (1+HEX_DIGEST_LEN+1+MAX_NICKNAME_LEN)
/** Maximum size, in bytes, for resized buffers. */
#define MAX_BUF_SIZE ((1<<24)-1) /* 16MB-1 */
/** Maximum size, in bytes, for any directory object that we've downloaded */
/** Maximum size, in bytes, for any directory object that we've downloaded. */
#define MAX_DIR_DL_SIZE MAX_BUF_SIZE
/** For http parsing: Maximum number of bytes we'll accept in the headers
* of an HTTP request or response.*/
* of an HTTP request or response. */
#define MAX_HEADERS_SIZE 50000
/** Maximum size, in bytes, for any directory object that we're accepting
* as an upload. */
......@@ -206,7 +206,7 @@
/** Possible rules for generating circuit IDs on an OR connection. */
typedef enum {
CIRC_ID_TYPE_LOWER=0, /**< Pick from 0..1<<15-1. */
CIRC_ID_TYPE_HIGHER=1, /**< Pick from 1<<15..1<<16-1 */
CIRC_ID_TYPE_HIGHER=1, /**< Pick from 1<<15..1<<16-1. */
/** The other side of a connection is an OP: never create circuits to it,
* and let it use any circuit ID it wants. */
CIRC_ID_TYPE_NEITHER=2
......@@ -293,7 +293,7 @@ typedef enum {
#define EXIT_CONN_STATE_RESOLVEFAILED 4
#define _EXIT_CONN_STATE_MAX 4
/* the AP state values must be disjoint from the EXIT state values */
/* The AP state values must be disjoint from the EXIT state values. */
#define _AP_CONN_STATE_MIN 5
/** State for a SOCKS connection: waiting for SOCKS request. */
#define AP_CONN_STATE_SOCKS_WAIT 5
......@@ -545,7 +545,7 @@ typedef enum {
* target address:port. */
#define END_STREAM_REASON_CANT_FETCH_ORIG_DEST 260
/** This is a connection on the NATD port, and the destination IP:Port was
* either ill-formed or out-of-range.*/
* either ill-formed or out-of-range. */
#define END_STREAM_REASON_INVALID_NATD_DEST 261
/** Bitwise-and this value with endreason to mask out all flags. */
......@@ -569,7 +569,7 @@ typedef enum {
* answer. */
#define REMAP_STREAM_SOURCE_EXIT 2
/* 'type' values to use in RESOLVED cells. Specified in tor-spec.txt */
/* 'type' values to use in RESOLVED cells. Specified in tor-spec.txt. */
#define RESOLVED_TYPE_HOSTNAME 0
#define RESOLVED_TYPE_IPV4 4
#define RESOLVED_TYPE_IPV6 6
......
......@@ -956,7 +956,7 @@ static uint32_t n_rend_client_ops = 0;
static uint32_t n_rend_mid_ops = 0;
static uint32_t n_rend_server_ops = 0;
/** Increment the count of the number of times we've done <b>operation</b> */
/** Increment the count of the number of times we've done <b>operation</b>. */
void
note_crypto_pk_op(pk_op_t operation)
{
......
......@@ -31,7 +31,7 @@ static time_t onionkey_set_at=0; /**< When was onionkey last changed? */
/** Current private onionskin decryption key: used to decode CREATE cells. */
static crypto_pk_env_t *onionkey=NULL;
/** Previous private onionskin decription key: used to decode CREATE cells
* generated by client that have an older version of our descriptor. */
* generated by clients that have an older version of our descriptor. */
static crypto_pk_env_t *lastonionkey=NULL;
/** Private "identity key": used to sign directory info and TLS
* certificates. Never changes. */
......@@ -1002,7 +1002,7 @@ check_descriptor_bandwidth_changed(time_t now)
}
/** Note at log level severity that our best guess of address has changed from
* <b>prev</b> to <b>cur</b> */
* <b>prev</b> to <b>cur</b>. */
static void
log_addr_has_changed(int severity, uint32_t prev, uint32_t cur)
{
......@@ -1053,7 +1053,7 @@ check_descriptor_ipaddress_changed(time_t now)
}
}
/** The most recently guessed value of our IP address, from directory
/** The most recently guessed value of our IP address, based on directory
* headers. */
static uint32_t last_guessed_ip = 0;
......
......@@ -216,7 +216,7 @@ router_append_to_journal(signed_descriptor_t *desc)
/** Sorting helper: return &lt;0, 0, or &gt;0 depending on whether the
* signed_descriptor_t* in *<b>a</b> is older, the same age as, or newer than
* the signed_descriptor_t* in *<b>b</b> */
* the signed_descriptor_t* in *<b>b</b>. */
static int
_compare_old_routers_by_age(const void **_a, const void **_b)
{
......@@ -226,7 +226,7 @@ _compare_old_routers_by_age(const void **_a, const void **_b)
/** Sorting helper: return &lt;0, 0, or &gt;0 depending on whether the
* routerinfo_t* in *<b>a</b> is older, the same age as, or newer than
* the routerinfo_t in *<b>b</b> */
* the routerinfo_t* in *<b>b</b>. */
static int
_compare_routers_by_age(const void **_a, const void **_b)
{
......@@ -1999,7 +1999,7 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
}
}
/* We haven't seen a router with this idntity before. Add it to the end of
/* We haven't seen a router with this identity before. Add it to the end of
* the list. */
routerlist_insert(routerlist, router);
if (!from_cache)
......@@ -2009,8 +2009,8 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
}
/** Sorting helper: return &lt;0, 0, or &gt;0 depending on whether the
* signed_descriptor_t* in *<b>a</b> has an identity digest preceeding, equal
* to, or later than that of <b>b</b>. */
* signed_descriptor_t* in *<b>a</b> has an identity digest preceding, equal
* to, or later than that of *<b>b</b>. */
static int
_compare_old_routers_by_identity(const void **_a, const void **_b)
{
......@@ -4144,9 +4144,9 @@ routerstatus_count_usable_entries(smartlist_t *entries)
/** True iff, the last time we checked whether we had enough directory info
* to build circuits, the answer was "yes". */
static int have_min_dir_info = 0;
/** True iff enough has changes since the last time we checked whether we had
/** True iff enough has changed since the last time we checked whether we had
* enough directory info to build circuits that our old answer can no longer
* be trusted. */
* be trusted. */
static int need_to_update_have_min_dir_info = 1;
/** Return true iff we have enough networkstatus and router information to
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment