r11278@catbus: nickm | 2007-01-23 14:22:27 -0500

 More doxygen comments: this time mainly around spooling and storing directory information.


svn:r9392

3 files changed, 58 insertions, 12 deletions

diff --git a/src/or/directory.c b/src/or/directory.c
index 8231ef7bf7..1ea605de1a 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -288,7 +288,9 @@ directory_initiate_command_routerstatus(routerstatus_t *status,
                              payload, payload_len);
 }
 
-/** DOCDOC */
+/** Return true iff <b>conn</b> is the client side of a directory connection
+ * we launched to ourself in order to determine the reachability of our
+ * dir_port. */
 static int
 directory_conn_is_self_reachability_test(dir_connection_t *conn)
 {
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 0551f9f6a9..f98419c4e5 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -977,7 +977,8 @@ set_cached_dir(cached_dir_t *d, char *directory, time_t when)
   }
 }
 
-/** DOCDOC */
+/** Decrement the reference count on <b>d</b>, and free it if it no longer has
+ * any references. */
 void
 cached_dir_decref(cached_dir_t *d)
 {
@@ -987,7 +988,8 @@ cached_dir_decref(cached_dir_t *d)
   tor_free(d);
 }
 
-/** DOCDOC */
+/** Allocate and return a new cached_dir_t containing the string <b>s</b>,
+ * published at <b>published</b>. */
 static cached_dir_t *
 new_cached_dir(char *s, time_t published)
 {
@@ -1325,12 +1327,17 @@ should_generate_v2_networkstatus(void)
     the_v2_networkstatus_is_dirty + DIR_REGEN_SLACK_TIME < time(NULL);
 }
 
+/* Thresholds for server performance: set by
+ * dirserv_compute_performance_thresholds, and used by
+ * generate_v2_networkstatus */
 static uint32_t stable_uptime = 0; /* start at a safe value */
 static uint32_t fast_bandwidth = 0;
 static uint32_t guard_bandwidth = 0;
 static uint64_t total_bandwidth = 0;
 static uint64_t total_exit_bandwidth = 0;
 
+/** Helper: estimate the uptime of a router given its stated uptime and the
+ * amount of time since it last stated its stated uptime. */
 static INLINE int
 real_uptime(routerinfo_t *router, time_t now)
 {
@@ -1359,6 +1366,8 @@ dirserv_thinks_router_is_unreliable(time_t now,
   return 0;
 }
 
+/** Helper: returns a tristate based on comparing **(uint32_t**)a to
+* **(uint32_t**)b. */
 static int
 _compare_uint32(const void **a, const void **b)
 {
@@ -1952,6 +1961,9 @@ dirserv_estimate_data_size(smartlist_t *fps, int is_serverdescs,
  * below this threshold. */
 #define DIRSERV_BUFFER_MIN 16384
 
+/** Spooling helper: called when we have no more data to spool to <b>conn</b>.
+ * Flushes any remaining data to be (un)compressed, and changes the spool
+ * source to NONE.  Returns 0 on success, negative on failure. */
 static int
 connection_dirserv_finish_spooling(dir_connection_t *conn)
 {
@@ -1964,7 +1976,12 @@ connection_dirserv_finish_spooling(dir_connection_t *conn)
   return 0;
 }
 
-/** DOCDOC */
+/** Spooling helper: called when we're sending a bunch of server descriptors,
+ * and the outbuf has become too empty. Pulls some entries from
+ * fingerprint_stack, and writes the corresponding servers onto outbuf.  If we
+ * run out of entries, flushes the zlib state and sets the spool source to
+ * NONE.  Returns 0 on success, negative on failure.
+ */
 static int
 connection_dirserv_add_servers_to_outbuf(dir_connection_t *conn)
 {
@@ -2014,7 +2031,12 @@ connection_dirserv_add_servers_to_outbuf(dir_connection_t *conn)
   return 0;
 }
 
-/** DOCDOC */
+/** Spooling helper: Called when we're sending a directory or networkstatus,
+ * and the outbuf has become too empty.  Pulls some bytes from
+ * <b>conn</b>-\>cached_dir-\>dir_z, uncompresses them if appropriate, and
+ * puts them on the outbuf.  If we run out of entries, flushes the zlib state
+ * and sets the spool source to NONE.  Returns 0 on success, negative on
+ * failure. */
 static int
 connection_dirserv_add_dir_bytes_to_outbuf(dir_connection_t *conn)
 {
@@ -2048,7 +2070,13 @@ connection_dirserv_add_dir_bytes_to_outbuf(dir_connection_t *conn)
   return 0;
 }
 
-/* DOCDOC */
+/* Spooling helper: Called when we're spooling networkstatus objects on
+ * <b>conn</b>, and the outbuf has become too empty.  If the current
+ * networkstatus object (in <b>conn</b>-\>cached_dir) has more data, pull data
+ * from there.  Otherwise, pop the next fingerprint from fingerprint_stack,
+ * and start spooling the next networkstatus.  If we run out of entries,
+ * flushes the zlib state and sets the spool source to NONE.  Returns 0 on
+ * success, negative on failure. */
 static int
 connection_dirserv_add_networkstatus_bytes_to_outbuf(dir_connection_t *conn)
 {
diff --git a/src/or/or.h b/src/or/or.h
index 0ef9425b04..f53555453d 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -524,9 +524,11 @@ typedef enum {
 #define RESOLVED_TYPE_ERROR_TRANSIENT 0xF0
 #define RESOLVED_TYPE_ERROR 0xF1
 
-/* DOCDOC We should document the meaning of these. */
-/* Negative reasons are internal */
+/* Negative reasons are internal: we never send them in a DESTROY or TRUNCATE
+ * call; they only go to the controller for tracking  */
+/** We couldn't build a path for this circuit. */
 #define END_CIRC_REASON_NOPATH          -2
+/** Catch-all "other" reason for closing origin circuits. */
 #define END_CIRC_AT_ORIGIN              -1
 
 /* Reasons why we (or a remote OR) might close a circuit. See tor-spec.txt for
@@ -811,13 +813,18 @@ typedef struct dir_connection_t {
   /* Used only for server sides of some dir connections, to implement
    * "spooling" of directory material to the outbuf.  Otherwise, we'd have
    * to append everything to the outbuf in one enormous chunk. */
+  /** What exactly are we spooling right now? */
   enum {
     DIR_SPOOL_NONE=0, DIR_SPOOL_SERVER_BY_DIGEST, DIR_SPOOL_SERVER_BY_FP,
     DIR_SPOOL_CACHED_DIR, DIR_SPOOL_NETWORKSTATUS
   } dir_spool_src;
+  /** List of fingerprints for networkstatuses or desriptors to be spooled. */
   smartlist_t *fingerprint_stack;
+  /** A cached_dir_t object that we're currently spooling out */
   struct cached_dir_t *cached_dir;
+  /** The current offset into cached_dir. */
   off_t cached_dir_offset;
+  /** The zlib object doing on-the-fly compression for spooled data. */
   tor_zlib_state_t *zlib_state;
 
   char rend_query[REND_SERVICE_ID_LEN+1]; /**< What rendezvous service are we
@@ -937,12 +944,21 @@ typedef enum {
 
 /** Information need to cache an onion router's descriptor. */
 typedef struct signed_descriptor_t {
+  /** Pointer to the raw server descriptor.  Not necessarily NUL-terminated.
+   * If saved_location is SAVED_IN_CACHE, this pointer is null.  */
   char *signed_descriptor_body;
+  /** Length of the server descriptor. */
   size_t signed_descriptor_len;
+  /** Digest of the server descriptor, computed as specified in dir-spec.txt */
   char signed_descriptor_digest[DIGEST_LEN];
+  /** Identity digest of the router. */
   char identity_digest[DIGEST_LEN];
+  /** Declared publication time of the descriptor */
   time_t published_on;
+  /** Where is the descriptor saved? */
   saved_location_t saved_location;
+  /** If saved_location is SAVED_IN_CACHE or SAVED_IN_JOURNAL, the offset of
+   * this descriptor in the corresponding file. */
   off_t saved_offset;
 } signed_descriptor_t;
 
@@ -2632,10 +2648,10 @@ 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 <b>desc</b> */
-  time_t received; /** When was the descriptor received? */
-  char *desc; /** Service descriptor */
-  rend_service_descriptor_t *parsed; /* Parsed value of 'desc' */
+  size_t len; /**< Length of <b>desc</b> */
+  time_t received; /**< When was the descriptor received? */
+  char *desc; /**< Service descriptor */
+  rend_service_descriptor_t *parsed; /**< Parsed value of 'desc' */
 } rend_cache_entry_t;
 
 void rend_cache_init(void);