More doxygenation.

svn:r1832

14 files changed, 235 insertions, 226 deletions

diff --git a/src/or/connection.c b/src/or/connection.c
index 6972c19bce..f993a71fff 100644
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -13,7 +13,7 @@
 
 extern or_options_t options; /**< command-line and config-file options */
 
-/** Array of strings to make conn->type human-readable */
+/** Array of strings to make conn-\>type human-readable */
 char *conn_type_to_string[] = {
   "",            /* 0 */
   "OP listener", /* 1 */
@@ -29,7 +29,7 @@ char *conn_type_to_string[] = {
   "CPU worker",  /* 11 */
 };
 
-/** Array of string arrays to make {conn->type,conn->state} human-readable */
+/** Array of string arrays to make {conn-\>type,conn-\>state} human-readable */
 char *conn_state_to_string[][_CONN_TYPE_MAX+1] = {
   { NULL }, /* no type associated with 0 */
   { NULL }, /* op listener, obsolete */
@@ -82,7 +82,7 @@ static int connection_receiver_bucket_should_increase(connection_t *conn);
 /** Allocate space for a new connection_t. This function just initializes
  * conn; you must call connection_add() to link it into the main array.
  *
- * Set conn->type to 'type'. Set conn->s and conn->poll_index to
+ * Set conn-\>type to <b>type</b>. Set conn-\>s and conn-\>poll_index to
  * -1 to signify they are not yet assigned.
  *
  * If conn is not a listener type, allocate buffers for it. If it's
@@ -357,7 +357,7 @@ int connection_create_listener(char *bindaddress, uint16_t bindport, int type) {
 }
 
 /** The listener connection <b>conn</b> told poll() it wanted to read.
- * Call accept() on conn->s, and add the new connection if necessary.
+ * Call accept() on conn-\>s, and add the new connection if necessary.
  */
 static int connection_handle_listener_read(connection_t *conn, int new_type) {
   int news; /* the new socket */
@@ -421,11 +421,11 @@ static int connection_init_accepted_conn(connection_t *conn) {
 
 /** Take conn, make a nonblocking socket; try to connect to
  * addr:port (they arrive in *host order*). If fail, return -1. Else
- * assign s to conn->s: if connected return 1, if eagain return 0.
+ * assign s to conn->\s: if connected return 1, if EAGAIN return 0.
  *
  * address is used to make the logs useful.
  *
- * On success, add 'conn' to the list of polled connections.
+ * On success, add conn to the list of polled connections.
  */
 int connection_connect(connection_t *conn, char *address, uint32_t addr, uint16_t port) {
   int s;
@@ -522,7 +522,7 @@ int retry_all_connections(void) {
   return 0;
 }
 
-extern int global_read_bucket; /**< from main.c */
+extern int global_read_bucket;
 
 /** How many bytes at most can we read onto this connection? */
 int connection_bucket_read_limit(connection_t *conn) {
@@ -643,7 +643,7 @@ static int connection_receiver_bucket_should_increase(connection_t *conn) {
   return 1;
 }
 
-/** Read bytes from conn->s and process them.
+/** Read bytes from conn->\s and process them.
  *
  * This function gets called from conn_read() in main.c, either
  * when poll() has declared that conn wants to read, or (for OR conns)
@@ -687,7 +687,7 @@ int connection_handle_read(connection_t *conn) {
   return 0;
 }
 
-/** Pull in new bytes from conn->s onto conn->inbuf, either
+/** Pull in new bytes from conn-\>s onto conn-\>inbuf, either
  * directly or via TLS. Reduce the token buckets by the number of
  * bytes read.
  *
@@ -745,7 +745,7 @@ int connection_fetch_from_buf(char *string, int len, connection_t *conn) {
   return fetch_from_buf(string, len, conn->inbuf);
 }
 
-/** Return conn->outbuf_flushlen: how many bytes conn wants to flush
+/** Return conn-\>outbuf_flushlen: how many bytes conn wants to flush
  * from its outbuf. */
 int connection_wants_to_flush(connection_t *conn) {
   return conn->outbuf_flushlen;
@@ -759,13 +759,13 @@ int connection_outbuf_too_full(connection_t *conn) {
   return (conn->outbuf_flushlen > 10*CELL_PAYLOAD_SIZE);
 }
 
-/** Try to flush more bytes onto conn->s.
+/** Try to flush more bytes onto conn-\>s.
  *
  * This function gets called either from conn_write() in main.c
  * when poll() has declared that conn wants to write, or below
  * from connection_write_to_buf() when an entire TLS record is ready.
  *
- * Update conn->timestamp_lastwritten to now, and call flush_buf
+ * Update conn-\>timestamp_lastwritten to now, and call flush_buf
  * or flush_buf_tls appropriately. If it succeeds and there no more
  * more bytes on conn->outbuf, then call connection_finished_flushing
  * on it too.
@@ -895,7 +895,7 @@ connection_t *connection_exact_get_by_addr_port(uint32_t addr, uint16_t port) {
 
 /** Find a connection to the router described by addr and port,
  * or alternately any router with the same identity key.
- * This connection *must* be in 'open' state.
+ * This connection <em>must</em> be in an "open" state.
  * If not, return NULL.
  */
 /* XXX this twin thing is busted, now that we're rotating onion
@@ -1013,7 +1013,7 @@ int connection_is_listener(connection_t *conn) {
   return 0;
 }
 
-/** Return 1 if <b>conn</b> is in state 'open' and is not marked
+/** Return 1 if <b>conn</b> is in state "open" and is not marked
  * for close, else return 0.
  */
 int connection_state_is_open(connection_t *conn) {
@@ -1030,7 +1030,7 @@ int connection_state_is_open(connection_t *conn) {
   return 0;
 }
 
-/** Write a 'destroy' cell with circ ID <b>circ_id</b> onto OR connection
+/** Write a destroy cell with circ ID <b>circ_id</b> onto OR connection
  * <b>conn</b>.
  *
  * Return 0.
@@ -1049,7 +1049,7 @@ int connection_send_destroy(uint16_t circ_id, connection_t *conn) {
   return 0;
 }
 
-/** Process new bytes that have arrived on conn->inbuf.
+/** Process new bytes that have arrived on conn-\>inbuf.
  *
  * This function just passes conn to the connection-specific
  * connection_*_process_inbuf() function.
@@ -1076,7 +1076,7 @@ int connection_process_inbuf(connection_t *conn) {
   }
 }
 
-/** We just finished flushing bytes from conn->outbuf, and there
+/** We just finished flushing bytes from conn-\>outbuf, and there
  * are no more bytes remaining.
  *
  * This function just passes conn to the connection-specific
diff --git a/src/or/connection_or.c b/src/or/connection_or.c
index 523ebd2fea..466024054f 100644
--- a/src/or/connection_or.c
+++ b/src/or/connection_or.c
@@ -59,10 +59,10 @@ int connection_or_process_inbuf(connection_t *conn) {
 /** Connection <b>conn</b> has finished writing and has no bytes left on
  * its outbuf.
  *
- * If it's in state 'connecting', then take a look at the socket, and
+ * If it's in state "connecting", then take a look at the socket, and
  * begin the tls handshake if the connect succeeded.
  *
- * Otherwise it's in state 'open': stop writing and return.
+ * Otherwise it's in state "open": stop writing and return.
  *
  * If <b>conn</b> is broken, mark it for close and return -1, else
  * return 0.
diff --git a/src/or/cpuworker.c b/src/or/cpuworker.c
index 53ff4a156d..d77c05b13c 100644
--- a/src/or/cpuworker.c
+++ b/src/or/cpuworker.c
@@ -61,7 +61,7 @@ static void tag_pack(char *tag, uint32_t addr, uint16_t port, uint16_t circ_id)
   *(uint16_t *)(tag+6) = circ_id;
 }
 
-/** Unpack 'tag' into addr, port, and circ_id.
+/** Unpack <b>tag</b> into addr, port, and circ_id.
  */
 static void tag_unpack(const char *tag, uint32_t *addr, uint16_t *port, uint16_t *circ_id) {
   struct in_addr in;
diff --git a/src/or/directory.c b/src/or/directory.c
index 2964e4e2c2..495f4822d6 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -27,14 +27,14 @@ char rend_fetch_url[] = "/rendezvous/";
 
 /********* END VARIABLES ************/
 
-/** Launch a new connection to the directory server 'router' to upload
- * or download a service or rendezvous descriptor. 'purpose' determines what
+/** Launch a new connection to the directory server <b>router</b> to upload or
+ * download a service or rendezvous descriptor. <b>purpose</b> determines what
  * kind of directory connection we're launching, and must be one of
  * DIR_PURPOSE_{FETCH|UPLOAD}_{DIR|RENDDESC}.
  *
- * When uploading, 'payload' and 'payload_len' determine the content
- * of the HTTP post.  When fetching a rendezvous descriptor, 'payload'
- * and 'payload_len' are the service ID we want to fetch.
+ * When uploading, <b>payload</b> and <b>payload_len</b> determine the content
+ * of the HTTP post.  When fetching a rendezvous descriptor, <b>payload</b>
+ * and <b>payload_len</b> are the service ID we want to fetch.
  */
 void directory_initiate_command(routerinfo_t *router, int purpose,
                                 const char *payload, int payload_len) {
@@ -118,8 +118,8 @@ void directory_initiate_command(routerinfo_t *router, int purpose,
   }
 }
 
-/** Queue an appropriate HTTP command on conn->outbuf.  The args
- * 'purpose', 'payload', and 'payload_len' are as in
+/** Queue an appropriate HTTP command on conn-\>outbuf.  The args
+ * <b>purpose</b>, <b>payload</b>, and <b>payload_len</b> are as in
  * directory_initiate_command.
  */
 static void directory_send_command(connection_t *conn, int purpose,
@@ -164,8 +164,8 @@ static void directory_send_command(connection_t *conn, int purpose,
   }
 }
 
-/** Parse an HTTP request string 'headers' of the form "%s %s HTTP/1..."
- * If it's well-formed, point *url to the second %s,
+/** Parse an HTTP request string <b>headers</b> of the form "\%s \%s HTTP/1..."
+ * If it's well-formed, point *<b>url</b> to the second \%s,
  * null-terminate it (this modifies headers!) and return 0.
  * Otherwise, return -1.
  */
@@ -186,8 +186,9 @@ int parse_http_url(char *headers, char **url) {
   return 0;
 }
 
-/** Parse an HTTP response string 'headers' of the form "HTTP/1.%d %d%s\r\n...".
- * If it's well-formed, assign *code, point *message to the first
+/** Parse an HTTP response string <b>headers</b> of the form
+ * "HTTP/1.\%d \%d\%s\r\n...".
+ * If it's well-formed, assign *<b>code</b>, point *<b>message</b> to the first
  * non-space character after code if there is one and message is non-NULL
  * (else leave it alone), and return 0.
  * Otherwise, return -1.
@@ -211,8 +212,8 @@ int parse_http_response(char *headers, int *code, char **message) {
   return 0;
 }
 
-/** Read handler for directory connections.  (That's connections *to*
- * directory servers and connections *at* directory servers.)
+/** Read handler for directory connections.  (That's connections <em>to</em>
+ * directory servers and connections <em>at</em> directory servers.)
  */
 int connection_dir_process_inbuf(connection_t *conn) {
   char *body;
@@ -365,7 +366,7 @@ static char answer503[] = "HTTP/1.0 503 Directory unavailable\r\n\r\n";
 /** Helper function: called when a dirserver gets a complete HTTP GET
  * request.  Look for a request for a directory or for a rendezvous
  * service descriptor.  On finding one, write a response into
- * conn->outbuf.  If the request is unrecognized, send a 404.
+ * conn-\>outbuf.  If the request is unrecognized, send a 404.
  * Always return 0. */
 static int directory_handle_command_get(connection_t *conn,
                                         char *headers, char *body,
@@ -431,7 +432,7 @@ static int directory_handle_command_get(connection_t *conn,
 /** Helper function: called when a dirserver gets a complete HTTP POST
  * request.  Look for an uploaded server descriptor or rendezvous
  * service descriptor.  On finding one, process it and write a
- * response into conn->outbuf.  If the request is unrecognized, send a
+ * response into conn-\>outbuf.  If the request is unrecognized, send a
  * 404.  Always return 0. */
 static int directory_handle_command_post(connection_t *conn,
                                          char *headers, char *body,
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 9c4612aea1..9959fe77b6 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -7,7 +7,7 @@
 /**
  * \file dirserv.c
  * \brief Directory server core implementation.
- *****/
+ **/
 
 /** How old do we allow a router to get before removing it? (seconds) */
 #define ROUTER_MAX_AGE (60*60*24)
@@ -30,13 +30,13 @@ typedef struct fingerprint_entry_t {
   char *fingerprint;
 } fingerprint_entry_t;
 
-/** List of nickname->identity fingerprint mappings for all the routers
+/** List of nickname-\>identity fingerprint mappings for all the routers
  * that we recognize. Used to prevent Sybil attacks. */
 static fingerprint_entry_t fingerprint_list[MAX_ROUTERS_IN_DIR];
 static int n_fingerprints = 0;
 
-/** Add the fingerprint 'fp' for the nickname 'nickname' to the global
- * list of recognized identity key fingerprints.
+/** Add the fingerprint <b>fp</b> for the nickname <b>nickname</b> to
+ * the global list of recognized identity key fingerprints.
  */
 void /* Should be static; exposed for testing */
 add_fingerprint_to_dir(const char *nickname, const char *fp)
@@ -68,11 +68,11 @@ dirserv_add_own_fingerprint(const char *nickname, crypto_pk_env_t *pk)
   return 0;
 }
 
-/** Parse the nickname->fingerprint mappings stored in the file named
- * 'fname'.  The file format is line-based, with each non-blank
+/** Parse the nickname-\>fingerprint mappings stored in the file named
+ * <b>fname</b>.  The file format is line-based, with each non-blank
  * holding one nickname, some space, and a fingerprint for that
  * nickname.  On success, replace the current fingerprint list with
- * the contents of 'fname' and return 0.  On failure, leave the
+ * the contents of <b>fname</b> and return 0.  On failure, leave the
  * current fingerprint list untouched, and return -1. */
 int
 dirserv_parse_fingerprint_file(const char *fname)
@@ -130,7 +130,7 @@ dirserv_parse_fingerprint_file(const char *fname)
   return -1;
 }
 
-/** Check whether 'router' has a nickname/identity key combination that
+/** Check whether <b>router</b> has a nickname/identity key combination that
  * we recognize from the fingerprint list.  Return 1 if router's
  * identity and nickname match, -1 if we recognize the nickname but
  * the identity key is wrong, and 0 if the nickname is not known. */
@@ -167,7 +167,7 @@ dirserv_router_fingerprint_is_known(const routerinfo_t *router)
   }
 }
 
-/** Return true iff any router named 'nickname' is in the fingerprint
+/** Return true iff any router named <b>nickname</b> is in the fingerprint
  * list. */
 static int
 router_nickname_is_approved(const char *nickname)
@@ -211,7 +211,7 @@ typedef struct descriptor_entry_t {
 static descriptor_entry_t *descriptor_list[MAX_ROUTERS_IN_DIR];
 static int n_descriptors = 0;
 
-/** Release the storage held by 'desc' */
+/** Release the storage held by <b>desc</b> */
 static void free_descriptor_entry(descriptor_entry_t *desc)
 {
   tor_free(desc->descriptor);
@@ -368,7 +368,7 @@ directory_remove_unrecognized(void)
   }
 }
 
-/** Mark the directory as 'dirty' -- when we're next asked for a
+/** Mark the directory as <b>dirty</b> -- when we're next asked for a
  * directory, we will rebuild it instead of reusing the most recently
  * generated one.
  */
@@ -379,7 +379,7 @@ directory_set_dirty()
 }
 
 /** Load all descriptors from an earlier directory stored in the string
- * 'dir'.
+ * <b>dir</b>.
  */
 int
 dirserv_init_from_directory_string(const char *dir)
@@ -397,7 +397,7 @@ dirserv_init_from_directory_string(const char *dir)
   return 0;
 }
 
-/** Set *nicknames_out to a comma-separated list of all the ORs that we
+/** Set *<b>nicknames_out</b> to a comma-separated list of all the ORs that we
  * believe are currently running (because we have open connections to
  * them).  Return 0 on success; -1 on error.
  */
@@ -462,9 +462,10 @@ dirserv_remove_old_servers(void)
   }
 }
 
-/** Dump all routers currently in the directory into the string <s>, using
- * at most <maxlen> characters, and signing the directory with <private_key>.
- * Return 0 on success, -1 on failure.
+/** Dump all routers currently in the directory into the string
+ * <b>s</b>, using at most <b>maxlen</b> characters, and signing the
+ * directory with <b>private_key</b>.  Return 0 on success, -1 on
+ * failure.
  */
 int
 dirserv_dump_directory_to_string(char *s, unsigned int maxlen,
@@ -536,11 +537,12 @@ dirserv_dump_directory_to_string(char *s, unsigned int maxlen,
   return -1;
 }
 
-/** XXX */
+/** Most recently generated encoded signed directory. */
 static char *the_directory = NULL;
 static int the_directory_len = -1;
 
-/** XXX */
+/** Set *<b>directory</b> to the most recently generated encoded signed
+ * directory, generating a new one as necessary. */
 size_t dirserv_get_directory(const char **directory)
 {
   char *new_directory;
diff --git a/src/or/dns.c b/src/or/dns.c
index e094ab884f..357a319a93 100644
--- a/src/or/dns.c
+++ b/src/or/dns.c
@@ -99,7 +99,7 @@ void dns_init(void) {
 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 <b>expire</b> time is before <b>now</b>
  * from the cache. */
 static void purge_expired_resolves(uint32_t now) {
   struct cached_resolve *resolve;
@@ -124,8 +124,8 @@ static void purge_expired_resolves(uint32_t now) {
   }
 }
 
-/** See if we have a cache entry for 'exitconn->address'. if so,
- * if resolve valid, put it into exitconn->addr and return 1.
+/** See if we have a cache entry for <b>exitconn</b>-\>address. if so,
+ * if resolve valid, put it into <b>exitconn</b>-\>addr and return 1.
  * If resolve failed, return -1.
  *
  * Else, if seen before and pending, add conn to the pending list,
@@ -206,7 +206,7 @@ int dns_resolve(connection_t *exitconn) {
 }
 
 /** Find or spawn a dns worker process to handle resolving
- * exitconn->address; tell that dns worker to begin resolving.
+ * <b>exitconn</b>-\>address; tell that dns worker to begin resolving.
  */
 static int assign_to_dnsworker(connection_t *exitconn) {
   connection_t *dnsconn;
@@ -240,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 <b>conn</b> from the list of connections waiting for conn-\>address.
  */
 void connection_dns_remove(connection_t *conn)
 {
@@ -313,9 +313,9 @@ void assert_all_pending_dns_resolves_ok(void) {
   }
 }
 
-/** 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.
+/** Mark all connections waiting for <b>address</b> for close.  Then cancel
+ * the resolve for <b>address</b> itself, and remove any cached results for
+ * <b>address</b> from the cache.
  */
 void dns_cancel_pending_resolve(char *address) {
   struct pending_connection_t *pend;
@@ -351,7 +351,7 @@ void dns_cancel_pending_resolve(char *address) {
   dns_purge_resolve(resolve);
 }
 
-/** Remove 'resolve' from the cache.
+/** Remove <b>resolve</b> from the cache.
  */
 static void dns_purge_resolve(struct cached_resolve *resolve) {
   struct cached_resolve *tmp;
@@ -379,9 +379,10 @@ static void dns_purge_resolve(struct cached_resolve *resolve) {
 
 /** 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
- * one of DNS_RESOLVE_{FAILED_TRANSIENT|FAILED_PERMANENT|SUCCEEDED}.
+ * cache the value.  (<b>address</b> is a NUL-terminated string containing the
+ * address to look up; <b>addr</b> is an IPv4 address in host order;
+ * <b>outcome</b> is one of
+ * DNS_RESOLVE_{FAILED_TRANSIENT|FAILED_PERMANENT|SUCCEEDED}.
  */
 static void dns_found_answer(char *address, uint32_t addr, char outcome) {
   struct pending_connection_t *pend;
@@ -459,9 +460,9 @@ 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. */
 int connection_dns_finished_flushing(connection_t *conn) {
@@ -518,12 +519,12 @@ int connection_dns_process_inbuf(connection_t *conn) {
  * execution context.  It takes as its argument an fdarray as returned
  * by socketpair(), and communicates via fdarray[1].  The protocol is
  * as follows:
- *     The OR says:
- *           ADDRESSLEN [1 byte]
- *           ADDRESS    [ADDRESSLEN bytes]
- *     The DNS worker does the lookup, and replies:
- *           OUTCOME    [1 byte]
- *           IP         [4 bytes]
+ *    - The OR says:
+ *         - ADDRESSLEN [1 byte]
+ *         - ADDRESS    [ADDRESSLEN bytes]
+ *    - The DNS worker does the lookup, and replies:
+ *         - OUTCOME    [1 byte]
+ *         - IP         [4 bytes]
  *
  * OUTCOME is one of DNS_RESOLVE_{FAILED_TRANSIENT|FAILED_PERMANENT|SUCCEEDED}.
  * IP is in host order.
diff --git a/src/or/main.c b/src/or/main.c
index dafd52e49e..8faf0ddda5 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -16,7 +16,7 @@ static int init_from_config(int argc, char **argv);
 
 /********* START VARIABLES **********/
 
-/** declared in connection.c */
+/* declared in connection.c */
 extern char *conn_state_to_string[][_CONN_TYPE_MAX+1];
 
 or_options_t options; /**< command-line and config-file options */
diff --git a/src/or/onion.c b/src/or/onion.c
index f30dbda12a..fa496421c0 100644
--- a/src/or/onion.c
+++ b/src/or/onion.c
@@ -9,8 +9,8 @@
 
 #include "or.h"
 
-/** prototypes for smartlist operations from routerlist.h
- * they're here to prevent precedence issues with the .h files
+/* prototypes for smartlist operations from routerlist.h
+ * They're here to prevent precedence issues with the .h files
  */
 void router_add_running_routers_to_smartlist(smartlist_t *sl);
 void add_nickname_list_to_smartlist(smartlist_t *sl, char *list);
diff --git a/src/or/rendclient.c b/src/or/rendclient.c
index ef3139e07a..796f3a2d60 100644
--- a/src/or/rendclient.c
+++ b/src/or/rendclient.c
@@ -218,7 +218,7 @@ rend_client_introduction_acked(circuit_t *circ,
 
 
 /** If we are not currently fetching a rendezvous service descriptor
- * for the service ID 'query', start a directory connection to fetch a
+ * for the service ID <b>query</b>, start a directory connection to fetch a
  * new one.
  */
 void
diff --git a/src/or/rendcommon.c b/src/or/rendcommon.c
index a2dda01ae8..b96557d494 100644
--- a/src/or/rendcommon.c
+++ b/src/or/rendcommon.c
@@ -10,7 +10,7 @@
 
 #include "or.h"
 
-/** Free the storage held by the service descriptor 'desc'.
+/** Free the storage held by the service descriptor <b>desc</b>.
  */
 void rend_service_descriptor_free(rend_service_descriptor_t *desc)
 {
@@ -26,8 +26,9 @@ void rend_service_descriptor_free(rend_service_descriptor_t *desc)
   tor_free(desc);
 }
 
-/** Encode a service descriptor for 'desc', and sign it with 'key'. Store
- * the descriptor in *str_out, and set *len_out to its length.
+/** Encode a service descriptor for <b>desc</b>, and sign it with
+ * <b>key</b>. Store the descriptor in *<b>str_out</b>, and set
+ * *<b>len_out</b> to its length.
  */
 int
 rend_encode_service_descriptor(rend_service_descriptor_t *desc,
@@ -72,9 +73,9 @@ rend_encode_service_descriptor(rend_service_descriptor_t *desc,
   return 0;
 }
 
-/** Parse a service descriptor at 'str' (len bytes).  On success,
- * return a newly alloced service_descriptor_t.  On failure, return
- * NULL.
+/** Parse a service descriptor at <b>str</b> (<b>len</b> bytes).  On
+ * success, return a newly alloced service_descriptor_t.  On failure,
+ * return NULL.
  */
 rend_service_descriptor_t *rend_parse_service_descriptor(
                            const char *str, int len)
@@ -129,9 +130,9 @@ rend_service_descriptor_t *rend_parse_service_descriptor(
   return NULL;
 }
 
-/** Sets out to the first 10 bytes of the digest of 'pk', base32
- * encoded.  NUL-terminates out.  (We use this string to identify
- * services in directory requests and .onion URLs.)
+/** Sets <b>out</b> to the first 10 bytes of the digest of <b>pk</b>,
+ * base32 encoded.  NUL-terminates out.  (We use this string to
+ * identify services in directory requests and .onion URLs.)
  */
 int rend_get_service_id(crypto_pk_env_t *pk, char *out)
 {
@@ -184,7 +185,7 @@ void rend_cache_clean(void)
   }
 }
 
-/** Return true iff 'query' is a syntactically valid service ID (as
+/** Return true iff <b>query</b> is a syntactically valid service ID (as
  * generated by rend_get_service_id).  */
 int rend_valid_service_id(const char *query) {
   if(strlen(query) != REND_SERVICE_ID_LEN)
@@ -196,8 +197,8 @@ int rend_valid_service_id(const char *query) {
   return 1;
 }
 
-/** If we have a cached rend_cache_entry_t for the service ID 'query', set
- * *e to that entry and return 1.  Else return 0.
+/** If we have a cached rend_cache_entry_t for the service ID <b>query</b>, set
+ * *<b>e</b> to that entry and return 1.  Else return 0.
  */
 int rend_cache_lookup_entry(const char *query, rend_cache_entry_t **e)
 {
@@ -210,11 +211,11 @@ int rend_cache_lookup_entry(const char *query, rend_cache_entry_t **e)
   return 1;
 }
 
-/** 'query' is a base-32'ed service id. If it's malformed, return -1.
+/** <b>query</b> is a base-32'ed service id. If it's malformed, return -1.
  * Else look it up.
- *   If it is found, point *desc to it, and write its length into
- *   *desc_len, and return 1.
- *   If it is not found, return 0.
+ *   - If it is found, point *desc to it, and write its length into
+ *     *desc_len, and return 1.
+ *   - If it is not found, return 0.
  * Note: calls to rend_cache_clean or rend_cache_store may invalidate
  * *desc.
  */
@@ -292,7 +293,7 @@ int rend_cache_store(const char *desc, int desc_len)
 }
 
 /** Called when we get a rendezvous-related relay cell on circuit
- * *circ.  Dispatch on rendezvous relay command. */
+ * <b>circ</b>.  Dispatch on rendezvous relay command. */
 void rend_process_relay_cell(circuit_t *circ, int command, int length,
                              const char *payload)
 {
diff --git a/src/or/rendservice.c b/src/or/rendservice.c
index afa69e0ea2..a84b6f38c7 100644
--- a/src/or/rendservice.c
+++ b/src/or/rendservice.c
@@ -44,7 +44,7 @@ typedef struct rend_service_t {
  */
 static smartlist_t *rend_service_list = NULL;
 
-/** Release the storage held by 'service'.
+/** Release the storage held by <b>service</b>.
  */
 static void rend_service_free(rend_service_t *service)
 {
@@ -78,7 +78,7 @@ static void rend_service_free_all(void)
   rend_service_list = smartlist_create();
 }
 
-/** Validate 'service' and add it to rend_service_list if possible.
+/** Validate <b>service<b> and add it to rend_service_list if possible.
  */
 static void add_service(rend_service_t *service)
 {
@@ -111,7 +111,8 @@ static void add_service(rend_service_t *service)
  * rend_service_port_config_t.
  *
  * The format is: VirtualPort (IP|RealPort|IP:RealPort)?
- *    IP defaults to 127.0.0.1; RealPort defaults to VirtualPort.
+ *
+ * IP defaults to 127.0.0.1; RealPort defaults to VirtualPort.
  */
 static rend_service_port_config_t *parse_port_config(const char *string)
 {
@@ -176,7 +177,7 @@ static rend_service_port_config_t *parse_port_config(const char *string)
 }
 
 /** Set up rend_service_list, based on the values of HiddenServiceDir and
- * HiddenServicePort in 'options'.  Return 0 on success and -1 on
+ * HiddenServicePort in <b>options</b>.  Return 0 on success and -1 on
  * failure.
  */
 int rend_config_services(or_options_t *options)
@@ -229,7 +230,7 @@ int rend_config_services(or_options_t *options)
   return 0;
 }
 
-/** Replace the old value of service->desc with one that reflects
+/** Replace the old value of <b>service</b>-\>desc with one that reflects
  * the other fields in service.
  */
 static void rend_service_update_descriptor(rend_service_t *service)
@@ -310,7 +311,7 @@ int rend_service_load_keys(void)
   return 0;
 }
 
-/** Return the service whose public key has a digest of 'digest'. Return
+/** Return the service whose public key has a digest of <b>digest</b>. Return
  * NULL if no such service exists.
  */
 static rend_service_t *
@@ -503,7 +504,7 @@ rend_service_relaunch_rendezvous(circuit_t *oldcirc)
 }
 
 /** Launch a circuit to serve as an introduction point for the service
- * 'service' at the introduction point 'nickname'
+ * <b>service</b> at the introduction point <b>nickname</b>
  */
 static int
 rend_service_launch_establish_intro(rend_service_t *service, const char *nickname)
@@ -687,12 +688,12 @@ rend_service_rendezvous_is_ready(circuit_t *circuit)
   circuit_mark_for_close(circuit);
 }
 
-/******
+/*
  * Manage introduction points
- ******/
+ */
 
 /** Return the (possibly non-open) introduction circuit ending at
- * 'router' for the service whose public key is 'pk_digest'.  Return
+ * <b>router</b> for the service whose public key is <b>pk_digest</b>.  Return
  * NULL if no such service is found.
  */
 static circuit_t *
@@ -722,7 +723,7 @@ find_intro_circuit(routerinfo_t *router, const char *pk_digest)
 }
 
 /** If the directory servers don't have an up-to-date descriptor for
- * 'service', Encode and sign the service descriptor for 'service',
+ * <b>service</b>, encode and sign the service descriptor for <b>service</b>,
  * and upload it to all the dirservers.
  */
 static void
@@ -841,8 +842,8 @@ void rend_services_introduce(void) {
 }
 
 /** Regenerate and upload rendezvous service descriptors for all
- * services.  If 'force' is false, skip services where we've already
- * uploaded an up-to-date copy; if 'force' is true, regenerate and
+ * services.  If <b>force</b> is false, skip services where we've already
+ * uploaded an up-to-date copy; if <b>force</b> is true, regenerate and
  * upload everything.
  */
 void
@@ -861,7 +862,7 @@ rend_services_upload(int force)
 }
 
 /** Log the status of introduction points for all rendezvous services
- * at log severity 'serverity'.
+ * at log severity <b>serverity</b>.
  */
 void
 rend_service_dump_stats(int severity)
@@ -893,9 +894,9 @@ rend_service_dump_stats(int severity)
   }
 }
 
-/** 'conn' is a rendezvous exit stream. Look up the hidden service for
- * 'circ', and look up the port and address based on conn->port.
- * Assign the actual conn->addr and conn->port. Return -1 if failure,
+/** Given <b>conn</a>, a rendezvous exit stream, look up the hidden service for
+ * 'circ', and look up the port and address based on conn-\>port.
+ * Assign the actual conn-\>addr and conn-\>port. Return -1 if failure,
  * or 0 for success.
  */
 int
diff --git a/src/or/rephist.c b/src/or/rephist.c
index 7ab0a72396..df737a65a6 100644
--- a/src/or/rephist.c
+++ b/src/or/rephist.c
@@ -2,49 +2,50 @@
 /* See LICENSE for licensing information */
 /* $Id$ */
 
-/*****
- * rephist.c: Basic history functionality for reputation module.
- *****/
+/**
+ * \file rephist.c
+ * \brief Basic history functionality for reputation module.
+ **/
 
 #include "or.h"
 
-/* History of an or->or link. */
+/** History of an OR-\>OR link. */
 typedef struct link_history_t {
-  /* When did we start tracking this list? */
+  /** When did we start tracking this list? */
   time_t since;
-  /* How many times did extending from OR1 to OR2 succeeed? */
+  /** How many times did extending from OR1 to OR2 succeeed? */
   unsigned long n_extend_ok;
-  /* How many times did extending from OR1 to OR2 fail? */
+  /** How many times did extending from OR1 to OR2 fail? */
   unsigned long n_extend_fail;
 } link_history_t;
 
-/* History of an OR. */
+/** History of an OR. */
 typedef struct or_history_t {
-  /* When did we start tracking this OR? */
+  /** When did we start tracking this OR? */
   time_t since;
-  /* How many times did we successfully connect? */
+  /** How many times did we successfully connect? */
   unsigned long n_conn_ok;
-  /*How many times did we try to connect and fail?*/
+  /** How many times did we try to connect and fail?*/
   unsigned long n_conn_fail;
-  /* How many seconds have we been connected to this OR before
+  /** How many seconds have we been connected to this OR before
    * 'up_since'? */
   unsigned long uptime;
-  /* How many seconds have we been unable to connect to this OR before
+  /** How many seconds have we been unable to connect to this OR before
    * 'down_since'? */
   unsigned long downtime;
-  /* If nonzero, we have been connected since this time. */
+  /** If nonzero, we have been connected since this time. */
   time_t up_since;
-  /* If nonzero, we have been unable to connect since this time. */
+  /** If nonzero, we have been unable to connect since this time. */
   time_t down_since;
-  /* Map from lowercased OR2 name to a link_history_t for the link
+  /** Map from lowercased OR2 name to a link_history_t for the link
    * from this OR to OR2. */
   strmap_t *link_history_map;
 } or_history_t;
 
-/* Map from lowercased OR nickname to or_history_t. */
+/** Map from lowercased OR nickname to or_history_t. */
 static strmap_t *history_map = NULL;
 
-/* Return the or_history_t for the named OR, creating it if necessary.
+/** Return the or_history_t for the named OR, creating it if necessary.
  */
 static or_history_t *get_or_history(const char* nickname)
 {
@@ -59,7 +60,7 @@ static or_history_t *get_or_history(const char* nickname)
   return hist;
 }
 
-/* Return the link_history_t for the link from the first named OR to
+/** Return the link_history_t for the link from the first named OR to
  * the second, creating it if necessary.
  */
 static link_history_t *get_link_history(const char *from_name,
@@ -77,8 +78,8 @@ static link_history_t *get_link_history(const char *from_name,
   return lhist;
 }
 
-/* Update an or_history_t object so that its uptime/downtime count is
- * up-to-date as of 'when'.
+/** Update an or_history_t object <b>hist</b> so that its uptime/downtime
+ * count is up-to-date as of <b>when</b>.
  */
 static void update_or_history(or_history_t *hist, time_t when)
 {
@@ -93,15 +94,15 @@ static void update_or_history(or_history_t *hist, time_t when)
   }
 }
 
-/* Initialize the static data structures for tracking history.
+/** Initialize the static data structures for tracking history.
  */
 void rep_hist_init(void)
 {
   history_map = strmap_new();
 }
 
-/* Remember that an attempt to connect to the OR 'nickname' failed at
- * 'when'.
+/** Remember that an attempt to connect to the OR <b>nickname</b> failed at
+ * <b>when</b>.
  */
 void rep_hist_note_connect_failed(const char* nickname, time_t when)
 {
@@ -116,8 +117,8 @@ void rep_hist_note_connect_failed(const char* nickname, time_t when)
     hist->down_since = when;
 }
 
-/* Remember that an attempt to connect to the OR 'nickname' succeeded
- * at 'when'.
+/** Remember that an attempt to connect to the OR <b>nickname</b> succeeded
+ * at <b>when</b>.
  */
 void rep_hist_note_connect_succeeded(const char* nickname, time_t when)
 {
@@ -132,8 +133,8 @@ void rep_hist_note_connect_succeeded(const char* nickname, time_t when)
     hist->up_since = when;
 }
 
-/* Remember that we intentionally closed our connection to the OR
- * 'nickname' at 'when'.
+/** Remember that we intentionally closed our connection to the OR
+ * <b>nickname</b> at <b>when</b>.
  */
 void rep_hist_note_disconnect(const char* nickname, time_t when)
 {
@@ -146,8 +147,8 @@ void rep_hist_note_disconnect(const char* nickname, time_t when)
   }
 }
 
-/* Remember that our connection to the OR 'nickname' had an error and
- * stopped working at 'when'.
+/** Remember that our connection to the OR <b>nickname</b> had an error and
+ * stopped working at <b>when</b>.
  */
 void rep_hist_note_connection_died(const char* nickname, time_t when)
 {
@@ -169,8 +170,8 @@ void rep_hist_note_connection_died(const char* nickname, time_t when)
     hist->down_since = when;
 }
 
-/* Remember that we successfully extended from the OR 'from_name' to
- * the OR 'to_name'.
+/** Remember that we successfully extended from the OR <b>from_name</b> to
+ * the OR <b>to_name</b>.
  */
 void rep_hist_note_extend_succeeded(const char *from_name,
                                     const char *to_name)
@@ -181,8 +182,8 @@ void rep_hist_note_extend_succeeded(const char *from_name,
   ++hist->n_extend_ok;
 }
 
-/* Remember that we tried to extend from the OR 'from_name' to the OR
- * 'to_name', but failed.
+/** Remember that we tried to extend from the OR <b>from_name</b> to the OR
+ * <b>to_name</b>, but failed.
  */
 void rep_hist_note_extend_failed(const char *from_name, const char *to_name)
 {
@@ -192,7 +193,7 @@ void rep_hist_note_extend_failed(const char *from_name, const char *to_name)
   ++hist->n_extend_fail;
 }
 
-/* Log all the reliability data we have rememberred, with the chosen
+/** Log all the reliability data we have rememberred, with the chosen
  * severity.
  */
 void rep_hist_dump_stats(time_t now, int severity)
diff --git a/src/or/router.c b/src/or/router.c
index e50d3832bb..51c4cdebf3 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -27,7 +27,7 @@ static crypto_pk_env_t *onionkey=NULL;
 static crypto_pk_env_t *lastonionkey=NULL;
 static crypto_pk_env_t *identitykey=NULL;
 
-/** Replace the current onion key with 'k'.  Does not affect lastonionkey;
+/** Replace the current onion key with <b>k</b>.  Does not affect lastonionkey;
  * to update onionkey correctly, call rotate_onion_key().
  */
 void set_onion_key(crypto_pk_env_t *k) {
@@ -108,9 +108,9 @@ void rotate_onion_key(void)
   log_fn(LOG_WARN, "Couldn't rotate onion key.");
 }
 
-/** Try to read an RSA key from 'fname'.  If 'fname' doesn't exist, create a new
- * RSA key and save it in 'fname'.  Return the read/created key, or NULL on
- * error.
+/** Try to read an RSA key from <b>fname</b>.  If <b>fname</b> doesn't exist,
+ * create a new RSA key and save it in <b>fname</b>.  Return the read/created
+ * key, or NULL on error.
  */
 crypto_pk_env_t *init_key_from_file(const char *fname)
 {
@@ -277,9 +277,9 @@ int init_keys(void) {
   return 0;
 }
 
-/*****
+/*
  * Clique maintenance
- *****/
+ */
 
 /** OR only: try to open connections to all of the other ORs we know about.
  */
@@ -301,9 +301,9 @@ void router_retry_connections(void) {
   }
 }
 
-/*****
+/*
  * OR descriptor generation.
- *****/
+ */
 
 /** my routerinfo. */
 static routerinfo_t *desc_routerinfo = NULL;
@@ -347,8 +347,8 @@ void router_post_to_dirservers(uint8_t purpose, const char *payload, int payload
   }
 }
 
-/** Append the comma-separated sequence of exit policies in 's' to the
- * exit policy in 'router'. */
+/** Append the comma-separated sequence of exit policies in <b>s</b> to the
+ * exit policy in <b>router</b>. */
 static void router_add_exit_policy_from_config_helper(const char *s, routerinfo_t *router) {
   char *e;
   int last=0;
@@ -384,9 +384,9 @@ static void router_add_exit_policy_from_config_helper(const char *s, routerinfo_
 
 #define DEFAULT_EXIT_POLICY "reject 0.0.0.0/8,reject 169.254.0.0/16,reject 127.0.0.0/8,reject 192.168.0.0/16,reject 10.0.0.0/8,reject 172.16.0.0/12,accept *:20-22,accept *:53,accept *:79-81,accept *:110,accept *:143,accept *:443,accept *:873,accept *:993,accept *:995,accept *:1024-65535,reject *:*"
 
-/** Set the exit policy on 'router' to match the exit policy in the current
- * configuration file.  If the exit policy doesn't have a catch-all rule,
- * then append the default exit policy as well.
+/** Set the exit policy on <b>router</b> to match the exit policy in the
+ * current configuration file.  If the exit policy doesn't have a catch-all
+ * rule, then append the default exit policy as well.
  */
 static void router_add_exit_policy_from_config(routerinfo_t *router) {
   router_add_exit_policy_from_config_helper(options.ExitPolicy, router);
@@ -413,8 +413,8 @@ int router_compare_to_my_exit_policy(connection_t *conn)
 
 }
 
-/** Return true iff 'router' has the same nickname as this OR.  (For an OP,
- * always returns false.)
+/** Return true iff <b>router</b> has the same nickname as this OR.  (For an
+ * OP, always returns false.)
  */
 int router_is_me(routerinfo_t *router)
 {
@@ -486,8 +486,8 @@ int router_rebuild_descriptor(void) {
   return 0;
 }
 
-/** Set 'platform' (max length 'len') to a NUL-terminated short string
- * describing the version of Tor and the operating system we're
+/** Set <b>platform</b> (max length <b>len</b>) to a NUL-terminated short
+ * string describing the version of Tor and the operating system we're
  * currently running on.
  */
 void get_platform_str(char *platform, int len)
@@ -503,10 +503,10 @@ void get_platform_str(char *platform, int len)
  */
 #define DEBUG_ROUTER_DUMP_ROUTER_TO_STRING
 
-/** OR only: Given a routerinfo for this router, and an identity key to
- * sign with, encode the routerinfo as a signed server descriptor and
- * write the result into 's', using at most 'maxlen' bytes.  Return -1
- * on failure, and the number of bytes used on success.
+/** OR only: Given a routerinfo for this router, and an identity key to sign
+ * with, encode the routerinfo as a signed server descriptor and write the
+ * result into <b>s</b>, using at most <b>maxlen</b> bytes.  Return -1 on
+ * failure, and the number of bytes used on success.
  */
 int router_dump_router_to_string(char *s, int maxlen, routerinfo_t *router,
                                  crypto_pk_env_t *ident_key) {
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 356e08c276..214264b08b 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -11,24 +11,18 @@
 
 /**
  * \file routerlist.c
+ *
  * \brief Code to parse descriptors and directories, and to
  * maintain and access the global list of routerinfos for known
  * servers.
  **/
 
-
 /****************************************************************************/
 
 extern or_options_t options; /**< command-line and config-file options */
 
 /****************************************************************************/
 
-/** We parse a directory by breaking it into "tokens", each consisting
- * of a keyword, a line full of arguments, and a binary object.  The
- * arguments and object are both optional, depending on the keyword
- * type.
- */
-
 /** Enumeration of possible token types.  The ones starting with K_
  * correspond to directory 'keywords'.  _UNRECOGNIZED is for an
  * unrecognized keyword; _ERR is an error in the tokenizing process,
@@ -58,7 +52,12 @@ typedef enum {
   _NIL
 } directory_keyword;
 
-/** Structure to hold a single directory tokon.
+/** Structure to hold a single directory token.
+ *
+ * We parse a directory by breaking it into "tokens", each consisting
+ * of a keyword, a line full of arguments, and a binary object.  The
+ * arguments and object are both optional, depending on the keyword
+ * type.
  */
 typedef struct directory_token_t {
   directory_keyword tp;        /**< Type of the token. */
@@ -223,8 +222,8 @@ static routerinfo_t *router_pick_directory_server_impl(void) {
 }
 
 /** Given a comma-and-whitespace separated list of nicknames, see which
- * nicknames in 'list' name routers in our routerlist that are
- * currently running.  Add the routerinfos for those routers to 'sl'.
+ * nicknames in <b>list</b> name routers in our routerlist that are
+ * currently running.  Add the routerinfos for those routers to <b>sl</b>.
  */
 void add_nickname_list_to_smartlist(smartlist_t *sl, const char *list) {
   const char *start,*end;
@@ -255,7 +254,8 @@ void add_nickname_list_to_smartlist(smartlist_t *sl, const char *list) {
   }
 }
 
-/** Add every router from our routerlist that is currently running to 'sl'.
+/** Add every router from our routerlist that is currently running to
+ * <b>sl</b>.
  */
 void router_add_running_routers_to_smartlist(smartlist_t *sl) {
   routerinfo_t *router;
@@ -273,10 +273,10 @@ void router_add_running_routers_to_smartlist(smartlist_t *sl) {
   }
 }
 
-/** Pick a random running router from a routerlist 'dir'.  If any node
- * named in 'preferred' is available, pick one of those.  Never pick a
- * node named in 'excluded', or whose routerinfo is in
- * 'excludedsmartlist', even if they are the only nodes available.
+/** Pick a random running router from a routerlist <b>dir</b>.  If any node
+ * named in <b>preferred</b> is available, pick one of those.  Never pick a
+ * node named in <b>excluded</b>, or whose routerinfo is in
+ * <b>excludedsmartlist</b>, even if they are the only nodes available.
  */
 routerinfo_t *router_choose_random_node(routerlist_t *dir,
                                         char *preferred, char *excluded,
@@ -311,8 +311,8 @@ routerinfo_t *router_choose_random_node(routerlist_t *dir,
   return choice;
 }
 
-/** Return the router in our routerlist whose address is 'addr' and
- * whose OR port is 'port'. Return NULL if no such router is known.
+/** Return the router in our routerlist whose address is <b>addr</b> and
+ * whose OR port is <b>port</b>. Return NULL if no such router is known.
  */
 routerinfo_t *router_get_by_addr_port(uint32_t addr, uint16_t port) {
   int i;
@@ -328,7 +328,7 @@ routerinfo_t *router_get_by_addr_port(uint32_t addr, uint16_t port) {
   return NULL;
 }
 
-/** Return the router in our routerlist whose nickname is 'nickname'
+/** Return the router in our routerlist whose nickname is <b>nickname</b>
  * (case insensitive).  Return NULL if no such router is known.
  */
 routerinfo_t *router_get_by_nickname(char *nickname)
@@ -347,12 +347,12 @@ routerinfo_t *router_get_by_nickname(char *nickname)
   return NULL;
 }
 
-/** Set *prouterlist to the current list of all known routers. */
+/** Set *<b>prouterlist</b> to the current list of all known routers. */
 void router_get_routerlist(routerlist_t **prouterlist) {
   *prouterlist = routerlist;
 }
 
-/** Free all storage held by 'router'. */
+/** Free all storage held by <b>router</b>. */
 void routerinfo_free(routerinfo_t *router)
 {
   struct exit_policy_t *e;
@@ -376,7 +376,7 @@ void routerinfo_free(routerinfo_t *router)
   free(router);
 }
 
-/** Allocate a fresh copy of 'router' */
+/** Allocate a fresh copy of <b>router</b> */
 routerinfo_t *routerinfo_copy(const routerinfo_t *router)
 {
   routerinfo_t *r;
@@ -403,7 +403,7 @@ routerinfo_t *routerinfo_copy(const routerinfo_t *router)
   return r;
 }
 
-/** Free all storage held by a routerlist 'rl' */
+/** Free all storage held by a routerlist <b>rl</b> */
 static void routerlist_free(routerlist_t *rl)
 {
   SMARTLIST_FOREACH(rl->routers, routerinfo_t *, r,
@@ -413,7 +413,7 @@ static void routerlist_free(routerlist_t *rl)
   tor_free(rl);
 }
 
-/** Mark the router named 'nickname' as non-running in our routerlist. */
+/** Mark the router named <b>nickname</b> as non-running in our routerlist. */
 void router_mark_as_down(char *nickname) {
   routerinfo_t *router = router_get_by_nickname(nickname);
   if(!router) /* we don't seem to know about him in the first place */
@@ -422,11 +422,12 @@ void router_mark_as_down(char *nickname) {
   router->is_running = 0;
 }
 
-/*****
+/*
  * Code to parse router descriptors and directories.
- *****/
+ */
 
-/** Replace the current router list with the one stored in 'routerfile'. */
+/** Replace the current router list with the one stored in
+ * <b>routerfile</b>. */
 int router_set_routerlist_from_file(char *routerfile)
 {
   char *string;
@@ -466,8 +467,8 @@ int router_set_routerlist_from_string(const char *s)
   return 0;
 }
 
-/** Set 'digest' to the SHA-1 digest of the hash of the directory in 's'.
- * Return 0 on success, nonzero on failure.
+/** Set <b>digest</b> to the SHA-1 digest of the hash of the directory in
+ * <b>s</b>.  Return 0 on success, nonzero on failure.
  */
 int router_get_dir_hash(const char *s, char *digest)
 {
@@ -475,8 +476,8 @@ int router_get_dir_hash(const char *s, char *digest)
                               "signed-directory","directory-signature");
 }
 
-/** Set 'digest' to the SHA-1 digest of the hash of the first router in 's'.
- * Return 0 on success, nonzero on failure.
+/** Set <b>digest</b> to the SHA-1 digest of the hash of the first router in
+ * <b>s</b>. Return 0 on success, nonzero on failure.
  */
 int router_get_router_hash(const char *s, char *digest)
 {
@@ -507,7 +508,7 @@ int is_recommended_version(const char *myversion,
 }
 
 /** Replace the current routerlist with the routers stored in the
- * signed directory 's'.  If pkey is provided, make sure that 's' is
+ * signed directory <b>s</b>.  If pkey is provided, make sure that <b>s</b> is
  * signed with pkey. */
 int router_set_routerlist_from_directory(const char *s, crypto_pk_env_t *pkey)
 {
@@ -535,7 +536,7 @@ int router_set_routerlist_from_directory(const char *s, crypto_pk_env_t *pkey)
   return 0;
 }
 
-/** Helper function: resolve the hostname for 'router'. */
+/** Helper function: resolve the hostname for <b>router</b>. */
 static int
 router_resolve(routerinfo_t *router)
 {
@@ -585,10 +586,10 @@ router_resolve_routerlist(routerlist_t *rl)
 }
 
 /** Decide whether a given addr:port is definitely accepted, definitely
- * rejected, or neither by a given exit policy.  If 'addr' is 0, we
+ * rejected, or neither by a given exit policy.  If <b>addr</b> is 0, we
  * don't know the IP of the target address.
  *
- * Returns -1 for 'rejected', 0 for accepted, 1 for 'maybe' (since IP is
+ * Returns -1 for "rejected", 0 for "accepted", 1 for "maybe" (since IP is
  * unknown).
  */
 int router_compare_addr_to_exit_policy(uint32_t addr, uint16_t port,
@@ -666,15 +667,15 @@ int router_exit_policy_all_routers_reject(uint32_t addr, uint16_t port) {
   return 1; /* all will reject. */
 }
 
-/** Return true iff 'router' does not permit exit streams.
+/** Return true iff <b>router</b> does not permit exit streams.
  */
 int router_exit_policy_rejects_all(routerinfo_t *router) {
   return router_compare_addr_to_exit_policy(0, 0, router->exit_policy)
     == ADDR_POLICY_REJECTED;
 }
 
-/** Parse a date of the format 'YYYY-MM-DD hh:mm:ss" and store the result into
- * *t.
+/** Parse a date of the format "YYYY-MM-DD hh:mm:ss" and store the result into
+ * *<b>t</b>.
  */
 /* XXX this should go in util.c, yes? -RD */
 static int parse_time(const char *cp, time_t *t)
@@ -706,9 +707,9 @@ static int parse_time(const char *cp, time_t *t)
 }
 
 
-/** Helper function: parse a directory from 's' and, when done, store the
- * resulting routerlist in *dest, freeing the old value if necessary.
- * If pkey is provided, we check the directory signature with pkey.
+/** Helper function: parse a directory from <b>s</b> and, when done, store the
+ * resulting routerlist in *<b>dest</b>, freeing the old value if necessary.
+ * If <b>pkey</b> is provided, we check the directory signature with pkey.
  */
 int /* Should be static; exposed for unit tests */
 router_get_routerlist_from_directory_impl(const char *str,
@@ -856,9 +857,9 @@ router_get_routerlist_from_directory_impl(const char *str,
   return r;
 }
 
-/** Helper function: Given a string *s containing a concatenated
+/** Helper function: Given a string *<b>s</b> containing a concatenated
  * sequence of router descriptors, parses them and stores the result
- * in *dest.  If good_nickname_lst is provided, then routers whose
+ * in *<b>dest</b>.  If good_nickname_lst is provided, then routers whose
  * nicknames are not listed are marked as nonrunning.  Advances *s to
  * a point immediately following the last router entry.  Returns 0 on
  * success and -1 on failure.
@@ -923,9 +924,9 @@ router_get_list_from_string_impl(const char **s, routerlist_t **dest,
 }
 
 
-/** Helper function: reads a single router entry from *s ... *end.
- * Mallocs a new router and returns it if all goes well, else returns
- * NULL.
+/** Helper function: reads a single router entry from *<b>s</b> ...
+ * *<b>end</b>.  Mallocs a new router and returns it if all goes well, else
+ * returns NULL.
  */
 routerinfo_t *router_get_entry_from_string(const char *s,
                                            const char *end) {
@@ -1120,7 +1121,7 @@ routerinfo_t *router_get_entry_from_string(const char *s,
   return router;
 }
 
-/** Parse the exit policy in the string 's' and add it to 'router'.
+/** Parse the exit policy in the string <b>s</b> and add it to <b>router</b>.
  */
 int
 router_add_exit_policy_from_string(routerinfo_t *router, const char *s)
@@ -1161,7 +1162,7 @@ router_add_exit_policy_from_string(routerinfo_t *router, const char *s)
 }
 
 /** Given a K_ACCEPT or K_REJECT token and a router, create a new exit_policy_t
- * corresponding to the token, and add it to 'router' */
+ * corresponding to the token, and add it to <b>router</b> */
 static int
 router_add_exit_policy(routerinfo_t *router, directory_token_t *tok) {
 
@@ -1278,12 +1279,12 @@ policy_read_failed:
   return -1;
 }
 
-/*****
+/*
  * Low-level tokenizer for router descriptors and directories.
- *****/
+ */
 
 
-/** Free all resources allocated for 'tok' */
+/** Free all resources allocated for <b>tok</b> */
 static void
 token_free(directory_token_t *tok)
 {
@@ -1487,8 +1488,8 @@ get_next_token(const char **s, where_syntax where) {
 #undef RET_ERR
 }
 
-/** Read all tokens from a string between 'start' and 'end', and add
- * them to 'out'.  If 'is_dir' is true, reject all non-directory
+/** Read all tokens from a string between <b>start</b> and <b>end</b>, and add
+ * them to <b>out</b>.  If <b>is_dir</b> is true, reject all non-directory
  * tokens; else reject all non-routerdescriptor tokens.
  */
 static int
@@ -1512,8 +1513,8 @@ tokenize_string(const char *start, const char *end, smartlist_t *out,
   return 0;
 }
 
-/** Find the first token in 's' whose keyword is 'keyword'; return NULL if no
- * such keyword is found.
+/** Find the first token in <b>s</b> whose keyword is <b>keyword</b>; return
+ * NULL if no such keyword is found.
  */
 static directory_token_t *
 find_first_by_keyword(smartlist_t *s, directory_keyword keyword)
@@ -1522,7 +1523,8 @@ find_first_by_keyword(smartlist_t *s, directory_keyword keyword)
   return NULL;
 }
 
-/** Return a newly allocated smartlist of all accept or reject tokens in 's'.
+/** Return a newly allocated smartlist of all accept or reject tokens in
+ * <b>s</b>.
  */
 static smartlist_t *
 find_all_exitpolicy(smartlist_t *s)
@@ -1535,10 +1537,10 @@ find_all_exitpolicy(smartlist_t *s)
 }
 
 
-/** Compute the SHA digest of the substring of s taken from the first
- * occurrence of start_str through the first newline after the first
- * subsequent occurrence of end_str; store the 20-byte result in 'digest';
- * return 0 on success.
+/** Compute the SHA digest of the substring of <b>s</b> taken from the first
+ * occurrence of <b>start_str</b> through the first newline after the first
+ * subsequent occurrence of <b>end_str</b>; store the 20-byte result in
+ * <b>digest</b>; return 0 on success.
  *
  * If no such substring exists, return -1.
  */