doxygen and other cleanups

svn:r13440

6 files changed, 28 insertions, 18 deletions

diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index c295d8aada..3216433a80 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -2822,15 +2822,23 @@ getinfo_helper_entry_guards(control_connection_t *conn,
   return 0;
 }
 
-/** DOCDOC arma */
+/** Information about a configured bridge. Currently this just matches the
+ * ones in the torrc file, but one day we may be able to learn about new
+ * bridges on our own, and remember them in the state file. */
 typedef struct {
+  /** IPv4 address of the bridge. */
   uint32_t addr;
+  /** TLS port for the bridge. */
   uint16_t port;
+  /** Expected identity digest, or all \0's if we don't know what the
+   * digest should be. */
   char identity[DIGEST_LEN];
+  /** When should we next try to fetch a descriptor for this bridge? */
   download_status_t fetch_status;
 } bridge_info_t;
 
-/** A list of known bridges. */
+/** A list of configured bridges. Whenever we actually get a descriptor
+ * for one, we add it as an entry guard. */
 static smartlist_t *bridge_list = NULL;
 
 /** Initialize the bridge list to empty, creating it if needed. */
diff --git a/src/or/connection_or.c b/src/or/connection_or.c
index f2bd54a494..79e7be2c21 100644
--- a/src/or/connection_or.c
+++ b/src/or/connection_or.c
@@ -174,13 +174,14 @@ var_cell_new(uint16_t payload_len)
   return cell;
 }
 
-/** Release all space held by <b>cell</b> */
+/** Release all space held by <b>cell</b>. */
 void
 var_cell_free(var_cell_t *cell)
 {
   tor_free(cell);
 }
 
+/** We've received an EOF from <b>conn</b>. Mark it for close and return. */
 int
 connection_or_reached_eof(or_connection_t *conn)
 {
diff --git a/src/or/directory.c b/src/or/directory.c
index 31e4d67d6c..8ca183cfe6 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -1876,7 +1876,7 @@ connection_dir_client_reached_eof(dir_connection_t *conn)
   return 0;
 }
 
-/** Called when a directory connection reaches EOF */
+/** Called when a directory connection reaches EOF. */
 int
 connection_dir_reached_eof(dir_connection_t *conn)
 {
diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c
index 972b16e0f2..6ac4e2c6ad 100644
--- a/src/or/networkstatus.c
+++ b/src/or/networkstatus.c
@@ -786,7 +786,7 @@ networkstatus_vote_find_entry(networkstatus_t *ns, const char *digest)
 /*XXXX make this static once functions are moved into this file. */
 /** Search the routerstatuses in <b>ns</b> for one whose identity digest is
  * <b>digest</b>.  Return value and set *<b>found_out</b> as for
- * smartlist_besearch_idx(). */
+ * smartlist_bsearch_idx(). */
 int
 networkstatus_vote_find_entry_idx(networkstatus_t *ns,
                                   const char *digest, int *found_out)
diff --git a/src/or/rephist.c b/src/or/rephist.c
index 6f973be61b..edeb43444f 100644
--- a/src/or/rephist.c
+++ b/src/or/rephist.c
@@ -19,9 +19,9 @@ static void bw_arrays_init(void);
 static void predicted_ports_init(void);
 static void hs_usage_init(void);
 
-/** Total number of bytes currently allocated in fields used by rephist.c */
+/** Total number of bytes currently allocated in fields used by rephist.c. */
 uint64_t rephist_total_alloc=0;
-/** Number of or_history_t obects currently allocated */
+/** Number of or_history_t objects currently allocated. */
 uint32_t rephist_total_num=0;
 
 /** If the total weighted run count of all runs for a router ever falls
diff --git a/src/or/test.c b/src/or/test.c
index 4b8081bf0f..d390009b8f 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -1081,20 +1081,20 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
 #define test_eq_ip6(a,b) _test_eq_ip6((a),(b),#a,#b,__LINE__)
 
 /** Helper: Assert that two strings both decode as IPv6 addresses with
- * tor_inet_pton, and both decode to the same address. */
+ * tor_inet_pton(), and both decode to the same address. */
 #define test_pton6_same(a,b) STMT_BEGIN                \
      test_eq(tor_inet_pton(AF_INET6, a, &a1), 1);      \
      test_eq(tor_inet_pton(AF_INET6, b, &a2), 1);      \
     _test_eq_ip6(&a1,&a2,#a,#b,__LINE__);              \
   STMT_END
 
-/** Helper: Assert that <b>a</b> is recognized as a bed IPv6 address by
- * tor_inet_pton. */
+/** Helper: Assert that <b>a</b> is recognized as a bad IPv6 address by
+ * tor_inet_pton(). */
 #define test_pton6_bad(a)                       \
   test_eq(0, tor_inet_pton(AF_INET6, a, &a1))
 
-/** Helper: assert that <b>a</b> when parsed by tor_inet_pton and displayed
- * with tor_inet_ntop, yields <b>b</b>. Also assert that <b>b</b> parses to
+/** Helper: assert that <b>a</b>, when parsed by tor_inet_pton() and displayed
+ * with tor_inet_ntop(), yields <b>b</b>. Also assert that <b>b</b> parses to
  * the same value as <b>a</b>. */
 #define test_ntop6_reduces(a,b) STMT_BEGIN                              \
     test_eq(tor_inet_pton(AF_INET6, a, &a1), 1);                        \
@@ -1103,8 +1103,8 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
     _test_eq_ip6(&a1, &a2, a, b, __LINE__);                             \
   STMT_END
 
-/** Helper: assert that <b>a</a> parses by tor_inet_pton into a address that
- * passes tor_addr_is_internal with for_listening */
+/** Helper: assert that <b>a</a> parses by tor_inet_pton() into a address that
+ * passes tor_addr_is_internal() with <b>for_listening</b> */
 #define test_internal_ip(a,for_listening) STMT_BEGIN           \
     test_eq(tor_inet_pton(AF_INET6, a, &t1.addr.in6_addr), 1); \
     t1.family = AF_INET6;                                      \
@@ -1112,8 +1112,8 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
       test_fail_msg( a "was not internal.");                   \
   STMT_END
 
-/** Helper: assert that <b>a</a> parses by tor_inet_pton into a address that
- * does not pass tor_addr_is_internal with for_listening. */
+/** Helper: assert that <b>a</a> parses by tor_inet_pton() into a address that
+ * does not pass tor_addr_is_internal() with <b>for_listening</b>. */
 #define test_external_ip(a,for_listening) STMT_BEGIN           \
     test_eq(tor_inet_pton(AF_INET6, a, &t1.addr.in6_addr), 1); \
     t1.family = AF_INET6;                                      \
@@ -1121,8 +1121,9 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
       test_fail_msg(a  "was not external.");                   \
   STMT_END
 
-/** Helper: Assert that a and b, when parsed by tor_inet_pton, give addresses
- * that compare in the order defined by op with tor_addr_compare(). */
+/** Helper: Assert that <b>a</b> and <b>b</b>, when parsed by
+ * tor_inet_pton(), give addresses that compare in the order defined by
+ * <b>op</b> with tor_addr_compare(). */
 #define test_addr_compare(a, op, b) STMT_BEGIN                    \
     test_eq(tor_inet_pton(AF_INET6, a, &t1.addr.in6_addr), 1);    \
     test_eq(tor_inet_pton(AF_INET6, b, &t2.addr.in6_addr), 1);    \