Make doxygen marginally happier

svn:r5208

8 files changed, 37 insertions, 17 deletions

diff --git a/src/or/buffers.c b/src/or/buffers.c
index e3b5c75ca2..093eb60e6a 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -49,6 +49,7 @@ const char buffers_c_id[] = "$Id$";
 #endif
 
 #define BUFFER_MAGIC 0xB0FFF312u
+/** 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 */
@@ -473,7 +474,7 @@ read_to_buf(int s, size_t at_most, buf_t *buf, int *reached_eof)
  * -1 on failure.
  */
 static INLINE int
-read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next)
+read_to_buf_tls_impl(tor_tls_t *tls, size_t at_most, buf_t *buf, char *next)
 {
   int r;
 
@@ -512,7 +513,7 @@ read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next)
  * ready to write -- or vice versa.
  */
 int
-read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf)
+read_to_buf_tls(tor_tls_t *tls, size_t at_most, buf_t *buf)
 {
   int r;
   char *next;
@@ -634,7 +635,7 @@ flush_buf(int s, buf_t *buf, size_t *buf_flushlen)
  * Return the number of bytes written on success, -1 on failure.
  */
 static INLINE int
-flush_buf_tls_impl(tor_tls *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
+flush_buf_tls_impl(tor_tls_t *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
 {
   int r;
 
@@ -652,7 +653,7 @@ flush_buf_tls_impl(tor_tls *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
 /** As flush_buf(), but writes data to a TLS connection.
  */
 int
-flush_buf_tls(tor_tls *tls, buf_t *buf, size_t *buf_flushlen)
+flush_buf_tls(tor_tls_t *tls, buf_t *buf, size_t *buf_flushlen)
 {
   int r;
   size_t flushed=0;
diff --git a/src/or/config.c b/src/or/config.c
index d7ac5f72c6..02fe7e4caf 100644
--- a/src/or/config.c
+++ b/src/or/config.c
@@ -36,7 +36,7 @@ typedef enum config_type_t {
   CONFIG_TYPE_OBSOLETE,     /**< Obsolete (ignored) option. */
 } config_type_t;
 
-/* An abbreviation for a configuration option allowed on the command line */
+/** An abbreviation for a configuration option allowed on the command line */
 typedef struct config_abbrev_t {
   const char *abbreviated;
   const char *full;
@@ -242,6 +242,9 @@ static config_var_description_t state_description[] = {
 
 typedef int (*validate_fn_t)(void*);
 
+/** Information on the keys, value types, key-to-struct-member mappings,
+ * variable descriptions, validation functions, and abbreviations for a
+ * configuration or storage format. */
 typedef struct {
   size_t size;
   uint32_t magic;
@@ -3087,6 +3090,8 @@ options_save_current(void)
   return write_configuration_file(get_default_conf_file(), get_options());
 }
 
+/** Mapping from a unit name to a multiplier for converting that unit into a
+ * base unit. */
 struct unit_table_t {
   const char *unit;
   uint64_t multiplier;
diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c
index 73aca5995a..431c6c8cdf 100644
--- a/src/or/connection_edge.c
+++ b/src/or/connection_edge.c
@@ -451,6 +451,7 @@ typedef struct {
   int num_resolve_failures;
 } addressmap_entry_t;
 
+/** Entry for mapping addresses to which virtual address we mapped them to. */
 typedef struct {
   char *ipv4_address;
   char *hostname_address;
@@ -1728,7 +1729,7 @@ connection_ap_can_use_exit(connection_t *conn, routerinfo_t *exit)
 /** A helper function for socks_policy_permits_address() below.
  *
  * Parse options->SocksPolicy in the same way that the exit policy
- * is parsed, and put the processed version in &socks_policy.
+ * is parsed, and put the processed version in socks_policy.
  * Ignore port specifiers.
  */
 void
@@ -1788,10 +1789,10 @@ set_exit_redirects(smartlist_t *lst)
 }
 
 /** If address is of the form "y.onion" with a well-formed handle y:
- *     Put a \code{'\0'} after y, lower-case it, and return ONION_HOSTNAME.
+ *     Put a NUL after y, lower-case it, and return ONION_HOSTNAME.
  *
  * If address is of the form "y.exit":
- *     Put a \code{'\0'} after y and return EXIT_HOSTNAME.
+ *     Put a NUL after y and return EXIT_HOSTNAME.
  *
  * Otherwise:
  *     Return NORMAL_HOSTNAME and change nothing.
diff --git a/src/or/connection_or.c b/src/or/connection_or.c
index 6d3fad21d0..9db1459ef7 100644
--- a/src/or/connection_or.c
+++ b/src/or/connection_or.c
@@ -379,7 +379,7 @@ connection_tls_start_handshake(connection_t *conn, int receiving)
 {
   conn->state = OR_CONN_STATE_HANDSHAKING;
   conn->tls = tor_tls_new(conn->s, receiving, 0);
-  if (!conn->tls) {
+  if (!conn->tls)
     log_fn(LOG_WARN,"tor_tls_new failed. Closing.");
     return -1;
   }
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 3a1c6eb079..76ea3c9fa6 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -78,13 +78,19 @@ parse_authdir_policy(void)
   }
 }
 
+/** A member of fingerprint_list: maps a name to a fingerprint.
+ **/
 typedef struct fingerprint_entry_t {
-  char *nickname;
+  char *nickname; /**< The name of a router (if this fingerprint is bound to a
+                   * name); the string "!reject" (if this fingerprint should
+                   * always be rejected); or the string "!invalid" (if this
+                   * fingerprint should be accepted but never marked as
+                   * valid. */
   char *fingerprint; /**< Stored as HEX_DIGEST_LEN characters, followed by a NUL */
 } fingerprint_entry_t;
 
 /** List of nickname-\>identity fingerprint mappings for all the routers
- * that we recognize. Used to prevent Sybil attacks. */
+ * that we name.  Used to prevent router impersonation. */
 /* Should be static; exposed for testing */
 smartlist_t *fingerprint_list = NULL;
 
diff --git a/src/or/onion.c b/src/or/onion.c
index d4aad3cfc9..c33f5e1aa4 100644
--- a/src/or/onion.c
+++ b/src/or/onion.c
@@ -13,6 +13,8 @@ const char onion_c_id[] = "$Id$";
 
 #include "or.h"
 
+/** Type for a linked list of circuits that are waiting for a free CPU worker
+ * to process a waiting onion handshake. */
 typedef struct onion_queue_t {
   circuit_t *circ;
   time_t when_added;
diff --git a/src/or/or.h b/src/or/or.h
index 254de738b8..58c57c14dd 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -644,7 +644,7 @@ struct connection_t {
   char *chosen_exit_name;
 
 /* Used only by OR connections: */
-  tor_tls *tls; /**< TLS connection state (OR only.) */
+  tor_tls_t *tls; /**< TLS connection state (OR only.) */
   uint16_t next_circ_id; /**< Which circ_id do we try to use next on
                           * this connection?  This is always in the
                           * range 0..1<<15-1. (OR only.)*/
@@ -1100,6 +1100,8 @@ typedef struct circuit_t circuit_t;
 #define ALLOW_UNVERIFIED_RENDEZVOUS   8
 #define ALLOW_UNVERIFIED_INTRODUCTION 16
 
+/** An entry specifying a set of addresses and ports that should be remapped
+ * to another address and port before exiting this exit node. */
 typedef struct exit_redirect_t {
   uint32_t addr;
   uint32_t mask;
@@ -1111,6 +1113,7 @@ typedef struct exit_redirect_t {
   unsigned is_redirect:1;
 } exit_redirect_t;
 
+/** A linked list of lines in a config file. */
 typedef struct config_line_t {
   char *key;
   char *value;
@@ -1341,10 +1344,10 @@ size_t buf_capacity(const buf_t *buf);
 const char *_buf_peek_raw_buffer(const buf_t *buf);
 
 int read_to_buf(int s, size_t at_most, buf_t *buf, int *reached_eof);
-int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf);
+int read_to_buf_tls(tor_tls_t *tls, size_t at_most, buf_t *buf);
 
 int flush_buf(int s, buf_t *buf, size_t *buf_flushlen);
-int flush_buf_tls(tor_tls *tls, buf_t *buf, size_t *buf_flushlen);
+int flush_buf_tls(tor_tls_t *tls, buf_t *buf, size_t *buf_flushlen);
 
 int write_to_buf(const char *string, size_t string_len, buf_t *buf);
 int fetch_from_buf(char *string, size_t string_len, buf_t *buf);
@@ -1965,10 +1968,11 @@ int rend_encode_service_descriptor(rend_service_descriptor_t *desc,
 rend_service_descriptor_t *rend_parse_service_descriptor(const char *str, size_t len);
 int rend_get_service_id(crypto_pk_env_t *pk, char *out);
 
+/** A cached rendezvous descriptor. */
 typedef struct rend_cache_entry_t {
-  size_t len; /* Length of desc */
-  time_t received; /* When was the descriptor received? */
-  char *desc; /* Service descriptor */
+  size_t len; /** Length of <b>desc</b> */
+  time_t received; /** When was the descriptor received? */
+  char *desc; /** Service descriptor */
   rend_service_descriptor_t *parsed; /* Parsed value of 'desc' */
 } rend_cache_entry_t;
 
diff --git a/src/or/router.c b/src/or/router.c
index 1475da03a0..c6dc7baf65 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -1175,3 +1175,4 @@ router_free_all(void)
     smartlist_free(warned_nonexistent_family);
   }
 }
+