more doxygen markup

plenty more remains


svn:r1824

1 files changed, 39 insertions, 35 deletions

diff --git a/src/or/dns.c b/src/or/dns.c
index 0c3d77edc2..e094ab884f 100644
--- a/src/or/dns.c
+++ b/src/or/dns.c
@@ -2,9 +2,10 @@
 /* See LICENSE for licensing information */
 /* $Id$ */
 
-/*****
- * dns.c: Resolve hostnames in separate processes.
- *****/
+/**
+ * \file dns.c
+ * \brief Resolve hostnames in separate processes.
+ **/
 
 /* See http://elvin.dstc.com/ListArchive/elvin-dev/archive/2001/09/msg00027.html
  * for some approaches to asynchronous dns. We will want to switch once one of
@@ -14,47 +15,49 @@
 #include "or.h"
 #include "tree.h"
 
-extern or_options_t options; /* command-line and config-file options */
+extern or_options_t options; /**< command-line and config-file options */
 
-/* Longest hostname we're willing to resolve. */
+/** Longest hostname we're willing to resolve. */
 #define MAX_ADDRESSLEN 256
 
-/* Maximum DNS processes to spawn. */
+/** Maximum DNS processes to spawn. */
 #define MAX_DNSWORKERS 50
-/* Minimum DNS processes to spawn. */
+/** Minimum DNS processes to spawn. */
 #define MIN_DNSWORKERS 3
 
-/* If more than this many processes are idle, shut down the extras. */
+/** If more than this many processes are idle, shut down the extras. */
 #define MAX_IDLE_DNSWORKERS 10
 
-/* Possible outcomes from hostname lookup: permanent failure,
+/** Possible outcomes from hostname lookup: permanent failure,
  * transient (retryable) failure, and success */
 #define DNS_RESOLVE_FAILED_TRANSIENT 1
 #define DNS_RESOLVE_FAILED_PERMANENT 2
 #define DNS_RESOLVE_SUCCEEDED 3
 
+/** How many dnsworkers we have running right now */
 int num_dnsworkers=0;
+/** How many of the running dnsworkers have an assigned task right now */
 int num_dnsworkers_busy=0;
 
-/* Linked list of connections waiting for a DNS answer. */
+/** Linked list of connections waiting for a DNS answer. */
 struct pending_connection_t {
   struct connection_t *conn;
   struct pending_connection_t *next;
 };
 
-/* A DNS request: possibly completed, possibly pending; cached_resolve
+/** A DNS request: possibly completed, possibly pending; cached_resolve
  * structs are stored at the OR side in a splay tree, and as a linked
  * list from oldest to newest.
  */
 struct cached_resolve {
   SPLAY_ENTRY(cached_resolve) node;
-  char address[MAX_ADDRESSLEN]; /* the hostname to be resolved */
-  uint32_t addr; /* in host order. I know I'm horrible for assuming ipv4 */
-  char state; /* 0 is pending; 1 means answer is valid; 2 means resolve failed */
+  char address[MAX_ADDRESSLEN]; /**< the hostname to be resolved */
+  uint32_t addr; /**< in host order. I know I'm horrible for assuming ipv4 */
+  char state; /**< 0 is pending; 1 means answer is valid; 2 means resolve failed */
 #define CACHE_STATE_PENDING 0
 #define CACHE_STATE_VALID 1
 #define CACHE_STATE_FAILED 2
-  uint32_t expire; /* remove items from cache after this time */
+  uint32_t expire; /**< remove items from cache after this time */
   struct pending_connection_t *pending_connections;
   struct cached_resolve *next;
 };
@@ -67,10 +70,10 @@ int dnsworker_main(void *data);
 static int spawn_dnsworker(void);
 static void spawn_enough_dnsworkers(void);
 
-/* Splay tree of cached_resolve objects */
+/** Splay tree of cached_resolve objects */
 static SPLAY_HEAD(cache_tree, cached_resolve) cache_root;
 
-/* Function to compare hashed resolves on their addresses; used to
+/** Function to compare hashed resolves on their addresses; used to
  * implement splay trees. */
 static int compare_cached_resolves(struct cached_resolve *a,
                                    struct cached_resolve *b) {
@@ -81,21 +84,22 @@ static int compare_cached_resolves(struct cached_resolve *a,
 SPLAY_PROTOTYPE(cache_tree, cached_resolve, node, compare_cached_resolves);
 SPLAY_GENERATE(cache_tree, cached_resolve, node, compare_cached_resolves);
 
-/* Initialize the DNS cache */
+/** Initialize the DNS cache */
 static void init_cache_tree(void) {
   SPLAY_INIT(&cache_root);
 }
 
-/* Initialize the DNS subsystem; called by the OR process. */
+/** Initialize the DNS subsystem; called by the OR process. */
 void dns_init(void) {
   init_cache_tree();
   spawn_enough_dnsworkers();
 }
 
-static struct cached_resolve *oldest_cached_resolve = NULL; /* linked list, */
-static struct cached_resolve *newest_cached_resolve = NULL; /* oldest to newest */
+/** linked list of resolved addresses, oldest to newest */
+static struct cached_resolve *oldest_cached_resolve = NULL;
+static struct cached_resolve *newest_cached_resolve = NULL;
 
-/* Remove every cached_resolve whose 'expire' time is before 'now'
+/** Remove every cached_resolve whose 'expire' time is before 'now'
  * from the cache. */
 static void purge_expired_resolves(uint32_t now) {
   struct cached_resolve *resolve;
@@ -120,7 +124,7 @@ static void purge_expired_resolves(uint32_t now) {
   }
 }
 
-/* See if we have a cache entry for 'exitconn->address'. if so,
+/** See if we have a cache entry for 'exitconn->address'. if so,
  * if resolve valid, put it into exitconn->addr and return 1.
  * If resolve failed, return -1.
  *
@@ -201,7 +205,7 @@ int dns_resolve(connection_t *exitconn) {
   return assign_to_dnsworker(exitconn);
 }
 
-/* Find or spawn a dns worker process to handle resolving
+/** Find or spawn a dns worker process to handle resolving
  * exitconn->address; tell that dns worker to begin resolving.
  */
 static int assign_to_dnsworker(connection_t *exitconn) {
@@ -236,7 +240,7 @@ static int assign_to_dnsworker(connection_t *exitconn) {
   return 0;
 }
 
-/* Remove 'conn' from the list of connections waiting for conn->address.
+/** Remove 'conn' from the list of connections waiting for conn->address.
  */
 void connection_dns_remove(connection_t *conn)
 {
@@ -279,7 +283,7 @@ void connection_dns_remove(connection_t *conn)
   }
 }
 
-/* Log an error and abort if conn is waiting for a DNS resolve.
+/** Log an error and abort if conn is waiting for a DNS resolve.
  */
 void assert_connection_edge_not_dns_pending(connection_t *conn) {
   struct pending_connection_t *pend;
@@ -294,7 +298,7 @@ void assert_connection_edge_not_dns_pending(connection_t *conn) {
   }
 }
 
-/* Log an error and abort if any connection waiting for a DNS resolve is
+/** Log an error and abort if any connection waiting for a DNS resolve is
  * corrupted. */
 void assert_all_pending_dns_resolves_ok(void) {
   struct pending_connection_t *pend;
@@ -309,7 +313,7 @@ void assert_all_pending_dns_resolves_ok(void) {
   }
 }
 
-/* Mark all connections waiting for 'address' for close.  Then cancel
+/** Mark all connections waiting for 'address' for close.  Then cancel
  * the resolve for 'address' itself, and remove any cached results for
  * 'address' from the cache.
  */
@@ -347,7 +351,7 @@ void dns_cancel_pending_resolve(char *address) {
   dns_purge_resolve(resolve);
 }
 
-/* Remove 'resolve' from the cache.
+/** Remove 'resolve' from the cache.
  */
 static void dns_purge_resolve(struct cached_resolve *resolve) {
   struct cached_resolve *tmp;
@@ -373,7 +377,7 @@ static void dns_purge_resolve(struct cached_resolve *resolve) {
   tor_free(resolve);
 }
 
-/* Called on the OR side when a DNS worker tells us the outcome of a DNS
+/** Called on the OR side when a DNS worker tells us the outcome of a DNS
  * resolve: tell all pending connections about the result of the lookup, and
  * cache the value.  ('address' is a NUL-terminated string containing the
  * address to look up; 'addr' is an IPv4 address in host order; 'outcome' is
@@ -459,14 +463,14 @@ static void dns_found_answer(char *address, uint32_t addr, char outcome) {
  * Connection between OR and dnsworker
  *****/
 
-/* Write handler: called when we've pushed a request to a dnsworker. */
+/** Write handler: called when we've pushed a request to a dnsworker. */
 int connection_dns_finished_flushing(connection_t *conn) {
   tor_assert(conn && conn->type == CONN_TYPE_DNSWORKER);
   connection_stop_writing(conn);
   return 0;
 }
 
-/* Read handler: called when we get data from a dnsworker.  If the
+/** Read handler: called when we get data from a dnsworker.  If the
  * connection is closed, mark the dnsworker as dead.  Otherwise, see
  * if we have a complete answer.  If so, call dns_found_answer on the
  * result.  If not, wait.  Returns 0. */
@@ -510,7 +514,7 @@ int connection_dns_process_inbuf(connection_t *conn) {
   return 0;
 }
 
-/* Implementation for DNS workers; this code runs in a separate
+/** Implementation for DNS workers; this code runs in a separate
  * execution context.  It takes as its argument an fdarray as returned
  * by socketpair(), and communicates via fdarray[1].  The protocol is
  * as follows:
@@ -578,7 +582,7 @@ int dnsworker_main(void *data) {
   return 0; /* windows wants this function to return an int */
 }
 
-/* Launch a new DNS worker; return 0 on success, -1 on failure.
+/** Launch a new DNS worker; return 0 on success, -1 on failure.
  */
 static int spawn_dnsworker(void) {
   int fd[2];
@@ -614,7 +618,7 @@ static int spawn_dnsworker(void) {
   return 0; /* success */
 }
 
-/* If we have too many or too few DNS workers, spawn or kill some.
+/** If we have too many or too few DNS workers, spawn or kill some.
  */
 static void spawn_enough_dnsworkers(void) {
   int num_dnsworkers_needed; /* aim to have 1 more than needed,