doc pedant

svn:r9634

src/common/compat.c

@@ -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)

src/common/torgzip.c

@@ -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)
 {

src/common/util.c

@@ -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. */

src/or/buffers.c

@@ -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->mem, yield a pointer to the raw memory region (for free(),
- * realloc(), and so on) */
+/** Given buf->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->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

src/or/circuitbuild.c

@@ -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)

src/or/circuituse.c

@@ -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;
 

src/or/config.c

@@ -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)
 {

src/or/control.c

@@ -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;

src/or/dirserv.c

@@ -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. */

src/or/main.c

@@ -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;

src/or/onion.c

@@ -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;

src/or/or.h

@@ -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

src/or/rephist.c

@@ -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)
 {

src/or/router.c

@@ -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;
 

src/or/routerlist.c

@@ -216,7 +216,7 @@ router_append_to_journal(signed_descriptor_t *desc)
 
 /** Sorting helper: return <0, 0, or >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