r11832@catbus: nickm | 2007-02-16 15:31:59 -0500

 Fix 35 remaining DOCDOC comments. Yowza.


svn:r9596

src/common/tortls.c

@@ -103,7 +103,8 @@ tls_log_errors(int severity, const char *doing)
   }
 }
 
-/** DOCDOC */
+/** Convert an errno (or a WSAerrno on windows) into a TOR_TLS_* error
+ * code. */
 static int
 tor_errno_to_tls_error(int e)
 {
@@ -206,7 +207,7 @@ tor_tls_init(void)
   }
 }
 
-/** DOCDOC */
+/** Free all global TLS structures. */
 void
 tor_tls_free_all(void)
 {
@@ -672,7 +673,7 @@ tor_tls_peer_has_cert(tor_tls_t *tls)
   return 1;
 }
 
-/** DOCDOC */
+/** Warn that a certificate lifetime extends through a certain range. */
 static void
 log_cert_lifetime(X509 *cert, const char *problem)
 {

src/common/util.c

@@ -862,9 +862,9 @@ tv_addms(struct timeval *a, long ms)
   a->tv_usec %= 1000000;
 }
 
-/** DOCDOC */
+/** Yield true iff <b>y</b> is a leap-year */
 #define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
-/** DOCDOC */
+/** Helper: Return the number of leap-days between Jan 1, y1 and Jan 1, y2. */
 static int
 n_leapdays(int y1, int y2)
 {
@@ -1957,11 +1957,12 @@ get_interface_address(int severity, uint32_t *addr)
 
 #ifndef MS_WINDOWS
 /* Based on code contributed by christian grothoff */
-/** DOCDOC */
+/** True iff we've called start_daemon. */
 static int start_daemon_called = 0;
-/** DOCDOC */
+/** True iff we've called finish_daemon. */
 static int finish_daemon_called = 0;
-/** DOCDOC */
+/** Socketpair used to communicate between parent and child process while
+ * daemonizing. */
 static int daemon_filedes[2];
 /** Start putting the process into daemon mode: fork and drop all resources
  * except standard fds.  The parent process never returns, but stays around

src/or/circuitbuild.c

@@ -1110,7 +1110,8 @@ router_handles_some_port(routerinfo_t *router, smartlist_t *needed_ports)
   return 0;
 }
 
-/* DOCDOC */
+/** Return true iff <b>conn</b> is waiting for a general circuit to be
+ * built. */
 static int
 ap_stream_wants_exit_attention(connection_t *conn)
 {

src/or/circuitlist.c

@@ -48,14 +48,15 @@ _orconn_circid_entries_eq(orconn_circid_circuit_map_t *a,
   return a->or_conn == b->or_conn && a->circ_id == b->circ_id;
 }
 
-/** DOCDOC */
+/** Helper: return a hash based on circuit ID and the pointer value of
+ * or_conn in <b>a</b>. */
 static INLINE unsigned int
 _orconn_circid_entry_hash(orconn_circid_circuit_map_t *a)
 {
   return (((unsigned)a->circ_id)<<16) ^ (unsigned)(uintptr_t)(a->or_conn);
 }
 
-/** DOCDOC */
+/** Map from [orconn,circid] to circuit. */
 static HT_HEAD(orconn_circid_map, orconn_circid_circuit_map_t)
      orconn_circid_circuit_map = HT_INITIALIZER();
 HT_PROTOTYPE(orconn_circid_map, orconn_circid_circuit_map_t, node,
@@ -319,7 +320,8 @@ origin_circuit_new(void)
   return circ;
 }
 
-/** DOCDOC */
+/** Allocate a new or_circuit_t, connected to <b>p_conn</b> as
+ * <b>p_circ_id</b>.  If <b>p_conn</b> is NULL, the circuit is unattached. */
 or_circuit_t *
 or_circuit_new(uint16_t p_circ_id, or_connection_t *p_conn)
 {

src/or/circuituse.c

@@ -566,10 +566,11 @@ circuit_expire_old_circuits(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Number of circuits to open at once when testing our bandwidth. */
 #define NUM_PARALLEL_TESTING_CIRCS 4
 
-/** DOCDOC */
+/** True iff we've ever opened enough testing circuits to test our
+ * bandwidth. */
 static int have_performed_bandwidth_test = 0;
 
 /** Reset have_performed_bandwidth_test, so we'll start building
@@ -776,7 +777,8 @@ circuit_build_failed(origin_circuit_t *circ)
  * circuit_launch_new and circuit_*_failure_count.
  */
 static int n_circuit_failures = 0;
-/** DOCDOC */
+/** Before the last time we called circuit_reset_failure_count(), were
+ * there a lot of failures? */
 static int did_circs_fail_last_period = 0;
 
 /** Don't retry launching a new circuit if we try this many times with no

src/or/dirserv.c

@@ -52,23 +52,24 @@ static void clear_cached_dir(cached_dir_t *d);
 #define FP_REJECT  4  /**< We will not publish this router. */
 #define FP_BADEXIT 8 /**< We'll tell clients not to use this as an exit. */
 
-/** DOCDOC */
+/** Encapsulate a nickname and an FP_* status; target of status_by_digest
+ * map. */
 typedef struct router_status_t {
   char nickname[MAX_NICKNAME_LEN+1];
   uint32_t status;
 } router_status_t;
 
 /** List of nickname-\>identity fingerprint mappings for all the routers
- * that we name.  Used to prevent router impersonation. DODDOC */
+ * that we name.  Used to prevent router impersonation. */
 typedef struct authdir_config_t {
   strmap_t *fp_by_name; /* Map from lc nickname to fingerprint */
-  digestmap_t *status_by_digest; /* Map from digest to FP_x mask */
+  digestmap_t *status_by_digest; /* Map from digest to router_status_t. */
 } authdir_config_t;
 
 /** Should be static; exposed for testing */
 authdir_config_t *fingerprint_list = NULL;
 
-/** DOCDOC */
+/** Allocate and return a new, empty, authdir_config_t. */
 static authdir_config_t *
 authdir_config_new(void)
 {
@@ -576,11 +577,12 @@ dirserv_add_descriptor(const char *desc, const char **msg)
   }
 }
 
-/** DOCDOC */
+/** Helper: return true iff the boolean values of <b>a</b> and <b>b</b> are
+ * different. */
 static INLINE int
 bool_neq(int a, int b)
 {
-  return (a && !b) || (!a && b);
+  return (a) ? !b : b;
 }
 
 /** Remove all descriptors whose nicknames or fingerprints no longer
@@ -1338,7 +1340,8 @@ dirserv_get_runningrouters(const char **rr, int compress)
 /** For authoritative directories: the current (v2) network status */
 static cached_dir_t *the_v2_networkstatus = NULL;
 
-/** DOCDOC */
+/** Return true iff our opinion of the routers has been stale for long
+ * enough that we should generate a new network status doc. */
 static int
 should_generate_v2_networkstatus(void)
 {
@@ -1488,11 +1491,11 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
 static cached_dir_t *
 generate_v2_networkstatus(void)
 {
-/** DOCDOC */
+/** Longest status flag name that we generate. */
 #define LONGEST_STATUS_FLAG_NAME_LEN 9
-/** DOCDOC */
-#define N_STATUS_FLAGS 9
-/** DOCDOC */
+/** Maximum number of status flags we'll apply to one router. */
+#define N_STATUS_FLAGS 10
+/** Amount of space to allocate for each entry. (r line and s line.) */
 #define RS_ENTRY_LEN                                                    \
   ( /* first line */                                                    \
    MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \

src/or/main.c

@@ -58,7 +58,8 @@ static time_t time_to_check_for_correct_dns = 0;
 /** Array of all open connections.  The first n_conns elements are valid. */
 static connection_t *connection_array[MAXCONNECTIONS+1] =
         { NULL };
-/** DOCDOC */
+/** List of connections that have been marked for close and need to be freed
+ * and removed from connection_array. */
 static smartlist_t *closeable_connection_lst = NULL;
 
 static int n_conns=0; /**< Number of connections currently active. */
@@ -818,7 +819,7 @@ run_scheduled_events(time_t now)
       if (any_trusted_dir_is_v1_authority())
         directory_get_from_dirserver(DIR_PURPOSE_FETCH_DIR, NULL, 1);
     }
-/** DOCDOC */
+/** How often do we (as a cache) fetch a new V1 directory? */
 #define V1_DIR_FETCH_PERIOD (6*60*60)
     time_to_fetch_directory = now + V1_DIR_FETCH_PERIOD;
   }
@@ -828,7 +829,7 @@ run_scheduled_events(time_t now)
     if (!authdir_mode(options) || !options->V1AuthoritativeDir) {
       directory_get_from_dirserver(DIR_PURPOSE_FETCH_RUNNING_LIST, NULL, 1);
     }
-/** DOCDOC */
+/** How often do we (as a cache) fetch a new V1 runningrouters document? */
 #define V1_RUNNINGROUTERS_FETCH_PERIOD (30*60)
     time_to_fetch_running_routers = now + V1_RUNNINGROUTERS_FETCH_PERIOD;
 
@@ -955,9 +956,9 @@ run_scheduled_events(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Libevent timer: used to invoke second_elapsed_callback once per second. */
 static struct event *timeout_event = NULL;
-/** DOCDOC */
+/** Number of libevent errors in the last second: we die if we get too many. */
 static int n_libevent_errors = 0;
 
 /** Libevent callback: invoked once every second. */

src/or/policies.c

@@ -156,7 +156,8 @@ addr_policy_permits_address(uint32_t addr, uint16_t port,
   }
 }
 
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make an OR connection to
+ * addr:port. */
 int
 fascist_firewall_allows_address_or(uint32_t addr, uint16_t port)
 {
@@ -164,7 +165,8 @@ fascist_firewall_allows_address_or(uint32_t addr, uint16_t port)
                                      reachable_or_addr_policy);
 }
 
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make a directory
+ * connection to addr:port. */
 int
 fascist_firewall_allows_address_dir(uint32_t addr, uint16_t port)
 {

src/or/router.c

@@ -28,13 +28,15 @@ extern long stats_n_seconds_working;
  */
 static tor_mutex_t *key_lock=NULL;
 static time_t onionkey_set_at=0; /**< When was onionkey last changed? */
-/** DOCDOC */
+/** Current private onionskin decryption key: used to decode CREATE cells. */
 static crypto_pk_env_t *onionkey=NULL;
-/** DOCDOC */
+/** Previous private onionskin decription key: used to decode CREATE cells
+ * generated by client that have an older version of our descriptor. */
 static crypto_pk_env_t *lastonionkey=NULL;
-/** DOCDOC */
+/** Private "identity key": used to sign directory info and TLS
+ * certificates. Never changes. */
 static crypto_pk_env_t *identitykey=NULL;
-/** DOCDOC */
+/** Digest of identitykey. */
 static char identitykey_digest[DIGEST_LEN];
 
 /** Replace the current onion key with <b>k</b>.  Does not affect lastonionkey;
@@ -999,7 +1001,8 @@ check_descriptor_bandwidth_changed(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Note at log level severity that our best guess of address has changed from
+ * <b>prev</b> to <b>cur</b>  */
 static void
 log_addr_has_changed(int severity, uint32_t prev, uint32_t cur)
 {
@@ -1050,7 +1053,8 @@ check_descriptor_ipaddress_changed(time_t now)
   }
 }
 
-/** DOCDOC */
+/** The most recently guessed value of our IP address, from directory
+ * headers. */
 static uint32_t last_guessed_ip = 0;
 
 /** A directory authority told us our IP address is <b>suggestion</b>.