Make doxygen marginally happier

svn:r5208

src/common/compat.c

@@ -776,6 +776,9 @@ get_uname(void)
  */
 
 #if defined(USE_PTHREADS)
+/** Wraps a an int (*)(void*) function and its argument so we can
+ * invoke them in a way pthreads would expect.
+ */
 typedef struct tor_pthread_data_t {
   int (*func)(void *);
   void *data;
@@ -961,6 +964,7 @@ tor_gmtime_r(const time_t *timep, struct tm *result)
 #endif
 
 #ifdef USE_WIN32_THREADS
+/** A generic lock structure for multithreaded builds. */
 struct tor_mutex_t {
   HANDLE handle;
 };
@@ -1010,6 +1014,7 @@ tor_get_thread_id(void)
   return (unsigned long)GetCurrentThreadId();
 }
 #elif defined(USE_PTHREADS)
+/** A generic lock structure for multithreaded builds. */
 struct tor_mutex_t {
   pthread_mutex_t mutex;
 };
@@ -1050,6 +1055,7 @@ tor_get_thread_id(void)
   return r.id;
 }
 #else
+/** A generic lock structure for multithreaded builds. */
 struct tor_mutex_t {
   int _unused;
 };

src/common/compat.h

@@ -236,6 +236,7 @@ void spawn_exit(void);
 
 /* Because we use threads instead of processes on Windows, we need locking on
  * Windows.  On Unixy platforms, these functions are no-ops. */
+
 typedef struct tor_mutex_t tor_mutex_t;
 #ifdef TOR_IS_MULTITHREADED
 tor_mutex_t *tor_mutex_new(void);

src/common/container.c

@@ -29,8 +29,9 @@ const char container_c_id[] = "$Id$";
 #define SMARTLIST_DEFAULT_CAPACITY 32
 
 #ifndef FAST_SMARTLIST
+/** A resizeable list of pointers, with associated helpful functionality. */
 struct smartlist_t {
-  /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
+  /* <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
    * before it needs to be resized.  Only the first <b>num_used</b> (\<=
    * capacity) elements point to valid data.
    */
@@ -484,14 +485,14 @@ smartlist_sort_strings(smartlist_t *sl)
   smartlist_sort(sl, _compare_string_ptrs);
 }
 
-/** Splay-tree implementation of string-to-void* map
+/** A node in a strmap_t string-to-void* map. */
- */
 typedef struct strmap_entry_t {
   SPLAY_ENTRY(strmap_entry_t) node;
   char *key;
   void *val;
 } strmap_entry_t;
 
+/** Splay-tree implementation of string-to-void* map */
 struct strmap_t {
   SPLAY_HEAD(strmap_tree, strmap_entry_t) head;
 };

src/common/crypto.c

@@ -91,18 +91,22 @@ static tor_mutex_t **_openssl_mutexes = NULL;
 static int _n_openssl_mutexes = -1;
 #endif
 
+/** A public key, or a public/private keypair. */
 struct crypto_pk_env_t
 {
   int refs; /* reference counting so we don't have to copy keys */
   RSA *key;
 };
 
+/** Key and stream information for a stream cipher. */
 struct crypto_cipher_env_t
 {
   char key[CIPHER_KEY_LEN];
   aes_cnt_cipher_t *cipher;
 };
 
+/** A structure to hold the first half (x, g^x) of a Diffie-Hellman handshake
+ * while we're waiting for the second.*/
 struct crypto_dh_env_t {
   DH *dh;
 };
@@ -1220,6 +1224,7 @@ crypto_digest(char *digest, const char *m, size_t len)
   return (SHA1((const unsigned char*)m,len,(unsigned char*)digest) == NULL);
 }
 
+/** Intermediate information about the digest of a stream of data. */
 struct crypto_digest_env_t {
   SHA_CTX d;
 };

src/common/crypto.h

@@ -24,7 +24,8 @@
 /** Length of our DH keys. */
 #define DH_BYTES (1024/8)
 
-/* DOCDOC */
+/** Length of a message digest when encoded in base64 with trailing = signs
+ * removed. */
 #define BASE64_DIGEST_LEN 27
 
 /** Constants used to indicate no padding for public-key encryption */

src/common/tortls.c

@@ -35,15 +35,16 @@ const char tortls_c_id[] = "$Id$";
 /** How long do identity certificates live? (sec) */
 #define IDENTITY_CERT_LIFETIME  (365*24*60*60)
 
-typedef struct tor_tls_context_st {
+/* DOCDOC */
+typedef struct tor_tls_context_t {
   SSL_CTX *ctx;
   SSL_CTX *client_only_ctx;
-} tor_tls_context;
+} tor_tls_context_t;
 
 /** Holds a SSL object and its associated data.  Members are only
  * accessed from within tortls.c.
  */
-struct tor_tls_st {
+struct tor_tls_t {
   SSL *ssl; /**< An OpenSSL SSL object. */
   int socket; /**< The underlying file descriptor for this TLS connection. */
   enum {
@@ -63,7 +64,7 @@ static X509* tor_tls_create_certificate(crypto_pk_env_t *rsa,
 
 /** Global tls context. We keep it here because nobody else needs to
  * touch it. */
-static tor_tls_context *global_tls_context = NULL;
+static tor_tls_context_t *global_tls_context = NULL;
 /** True iff tor_tls_init() has been called. */
 static int tls_library_is_initialized = 0;
 
@@ -111,7 +112,7 @@ tls_log_errors(int severity, const char *doing)
  * current action as <b>doing</b>.
  */
 static int
-tor_tls_get_error(tor_tls *tls, int r, int extra,
+tor_tls_get_error(tor_tls_t *tls, int r, int extra,
                   const char *doing, int severity)
 {
   int err = SSL_get_error(tls->ssl, r);
@@ -308,7 +309,7 @@ tor_tls_context_new(crypto_pk_env_t *identity,
   crypto_pk_env_t *rsa = NULL;
   crypto_dh_env_t *dh = NULL;
   EVP_PKEY *pkey = NULL;
-  tor_tls_context *result = NULL;
+  tor_tls_context_t *result = NULL;
   X509 *cert = NULL, *idcert = NULL;
   char nn2[128];
   int client_only;
@@ -337,7 +338,7 @@ tor_tls_context_new(crypto_pk_env_t *identity,
     }
   }
 
-  result = tor_malloc(sizeof(tor_tls_context));
+  result = tor_malloc(sizeof(tor_tls_context_t));
   result->ctx = result->client_only_ctx = NULL;
   for (client_only=0; client_only <= 1; ++client_only) {
     ctx = client_only ? &result->client_only_ctx : &result->ctx;
@@ -419,10 +420,10 @@ tor_tls_context_new(crypto_pk_env_t *identity,
 /** Create a new TLS object from a file descriptor, and a flag to
  * determine whether it is functioning as a server.
  */
-tor_tls *
+tor_tls_t *
 tor_tls_new(int sock, int isServer, int use_no_cert)
 {
-  tor_tls *result = tor_malloc(sizeof(tor_tls));
+  tor_tls_t *result = tor_malloc(sizeof(tor_tls_t));
   SSL_CTX *ctx;
   tor_assert(global_tls_context); /* make sure somebody made it first */
   ctx = use_no_cert ? global_tls_context->client_only_ctx
@@ -445,7 +446,7 @@ tor_tls_new(int sock, int isServer, int use_no_cert)
 /** Return whether this tls initiated the connect (client) or
  * received it (server). */
 int
-tor_tls_is_server(tor_tls *tls)
+tor_tls_is_server(tor_tls_t *tls)
 {
   tor_assert(tls);
   return tls->isServer;
@@ -455,7 +456,7 @@ tor_tls_is_server(tor_tls *tls)
  * underlying file descriptor.
  */
 void
-tor_tls_free(tor_tls *tls)
+tor_tls_free(tor_tls_t *tls)
 {
   tor_assert(tls && tls->ssl);
   SSL_free(tls->ssl);
@@ -469,7 +470,7 @@ tor_tls_free(tor_tls *tls)
  * TOR_TLS_CLOSE, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.
  */
 int
-tor_tls_read(tor_tls *tls, char *cp, size_t len)
+tor_tls_read(tor_tls_t *tls, char *cp, size_t len)
 {
   int r, err;
   tor_assert(tls);
@@ -496,7 +497,7 @@ tor_tls_read(tor_tls *tls, char *cp, size_t len)
  * TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.
  */
 int
-tor_tls_write(tor_tls *tls, char *cp, size_t n)
+tor_tls_write(tor_tls_t *tls, char *cp, size_t n)
 {
   int r, err;
   tor_assert(tls);
@@ -528,7 +529,7 @@ tor_tls_write(tor_tls *tls, char *cp, size_t n)
  * or TOR_TLS_WANTWRITE.
  */
 int
-tor_tls_handshake(tor_tls *tls)
+tor_tls_handshake(tor_tls_t *tls)
 {
   int r;
   tor_assert(tls);
@@ -556,7 +557,7 @@ tor_tls_handshake(tor_tls *tls)
  * or TOR_TLS_WANTWRITE.
  */
 int
-tor_tls_shutdown(tor_tls *tls)
+tor_tls_shutdown(tor_tls_t *tls)
 {
   int r, err;
   char buf[128];
@@ -616,7 +617,7 @@ tor_tls_shutdown(tor_tls *tls)
 /** Return true iff this TLS connection is authenticated.
  */
 int
-tor_tls_peer_has_cert(tor_tls *tls)
+tor_tls_peer_has_cert(tor_tls_t *tls)
 {
   X509 *cert;
   cert = SSL_get_peer_certificate(tls->ssl);
@@ -633,7 +634,7 @@ tor_tls_peer_has_cert(tor_tls *tls)
  * NUL-terminate.  Return 0 on success, -1 on failure.
  */
 int
-tor_tls_get_peer_cert_nickname(tor_tls *tls, char *buf, size_t buflen)
+tor_tls_get_peer_cert_nickname(tor_tls_t *tls, char *buf, size_t buflen)
 {
   X509 *cert = NULL;
   X509_NAME *name = NULL;
@@ -726,7 +727,7 @@ log_cert_lifetime(X509 *cert, const char *problem)
  * 0.  Else, return -1.
  */
 int
-tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity_key)
+tor_tls_verify(tor_tls_t *tls, crypto_pk_env_t **identity_key)
 {
   X509 *cert = NULL, *id_cert = NULL;
   STACK_OF(X509) *chain = NULL;
@@ -795,7 +796,7 @@ tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity_key)
  * NOTE: you should call tor_tls_verify before tor_tls_check_lifetime.
  */
 int
-tor_tls_check_lifetime(tor_tls *tls, int tolerance)
+tor_tls_check_lifetime(tor_tls_t *tls, int tolerance)
 {
   time_t now, t;
   X509 *cert;
@@ -830,7 +831,7 @@ tor_tls_check_lifetime(tor_tls *tls, int tolerance)
 /** Return the number of bytes available for reading from <b>tls</b>.
  */
 int
-tor_tls_get_pending_bytes(tor_tls *tls)
+tor_tls_get_pending_bytes(tor_tls_t *tls)
 {
   tor_assert(tls);
 #if OPENSSL_VERSION_NUMBER < 0x0090700fl
@@ -845,14 +846,14 @@ tor_tls_get_pending_bytes(tor_tls *tls)
 
 /** Return the number of bytes read across the underlying socket. */
 unsigned long
-tor_tls_get_n_bytes_read(tor_tls *tls)
+tor_tls_get_n_bytes_read(tor_tls_t *tls)
 {
   tor_assert(tls);
   return BIO_number_read(SSL_get_rbio(tls->ssl));
 }
 /** Return the number of bytes written across the underlying socket. */
 unsigned long
-tor_tls_get_n_bytes_written(tor_tls *tls)
+tor_tls_get_n_bytes_written(tor_tls_t *tls)
 {
   tor_assert(tls);
   return BIO_number_written(SSL_get_wbio(tls->ssl));

src/common/tortls.h

@@ -16,7 +16,7 @@
 #include "../common/compat.h"
 
 /* Opaque structure to hold a TLS connection. */
-typedef struct tor_tls_st tor_tls;
+typedef struct tor_tls_t tor_tls_t;
 
 /* Possible return values for most tor_tls_* functions. */
 #define TOR_TLS_ERROR       -4
@@ -28,21 +28,21 @@ typedef struct tor_tls_st tor_tls;
 void tor_tls_free_all(void);
 int tor_tls_context_new(crypto_pk_env_t *rsa, int isServer,
                         const char *nickname, unsigned int key_lifetime);
-tor_tls *tor_tls_new(int sock, int is_server, int use_no_cert);
+tor_tls_t *tor_tls_new(int sock, int is_server, int use_no_cert);
-int tor_tls_is_server(tor_tls *tls);
+int tor_tls_is_server(tor_tls_t *tls);
-void tor_tls_free(tor_tls *tls);
+void tor_tls_free(tor_tls_t *tls);
-int tor_tls_peer_has_cert(tor_tls *tls);
+int tor_tls_peer_has_cert(tor_tls_t *tls);
-int tor_tls_get_peer_cert_nickname(tor_tls *tls, char *buf, size_t buflen);
+int tor_tls_get_peer_cert_nickname(tor_tls_t *tls, char *buf, size_t buflen);
-int tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity);
+int tor_tls_verify(tor_tls_t *tls, crypto_pk_env_t **identity);
-int tor_tls_check_lifetime(tor_tls *tls, int tolerance);
+int tor_tls_check_lifetime(tor_tls_t *tls, int tolerance);
-int tor_tls_read(tor_tls *tls, char *cp, size_t len);
+int tor_tls_read(tor_tls_t *tls, char *cp, size_t len);
-int tor_tls_write(tor_tls *tls, char *cp, size_t n);
+int tor_tls_write(tor_tls_t *tls, char *cp, size_t n);
-int tor_tls_handshake(tor_tls *tls);
+int tor_tls_handshake(tor_tls_t *tls);
-int tor_tls_shutdown(tor_tls *tls);
+int tor_tls_shutdown(tor_tls_t *tls);
-int tor_tls_get_pending_bytes(tor_tls *tls);
+int tor_tls_get_pending_bytes(tor_tls_t *tls);
 
-unsigned long tor_tls_get_n_bytes_read(tor_tls *tls);
+unsigned long tor_tls_get_n_bytes_read(tor_tls_t *tls);
-unsigned long tor_tls_get_n_bytes_written(tor_tls *tls);
+unsigned long tor_tls_get_n_bytes_written(tor_tls_t *tls);
 
 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
  */

src/common/util.h

@@ -140,6 +140,8 @@ int check_private_dir(const char *dirname, cpd_check_t check);
 int write_str_to_file(const char *fname, const char *str, int bin);
 int write_bytes_to_file(const char *fname, const char *str, size_t len,
                         int bin);
+/** An ad-hoc type to hold a string of characters and a count; used by
+ * write_chunks_to_file. */
 typedef struct sized_chunk_t {
   const char *bytes;
   size_t len;

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;

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;

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.

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

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;
 

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;

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 */
+  size_t len; /** Length of <b>desc</b> */
-  time_t received; /* When was the descriptor received? */
+  time_t received; /** When was the descriptor received? */
-  char *desc; /* Service descriptor */
+  char *desc; /** Service descriptor */
   rend_service_descriptor_t *parsed; /* Parsed value of 'desc' */
 } rend_cache_entry_t;
 

src/or/router.c

@@ -1175,3 +1175,4 @@ router_free_all(void)
     smartlist_free(warned_nonexistent_family);
   }
 }
+