whitespace and docs

svn:r6808

src/or/rephist.c

@@ -83,7 +83,7 @@ get_or_history(const char* id)
 
 /** Return the link_history_t for the link from the first named OR to
  * the second, creating it if necessary. (ORs are identified by
- * identity digest)
+ * identity digest.)
  */
 static link_history_t *
 get_link_history(const char *from_id, const char *to_id)
@@ -105,7 +105,7 @@ get_link_history(const char *from_id, const char *to_id)
   return lhist;
 }
 
-/** Helper: free storage held by a single link history entry */
+/** Helper: free storage held by a single link history entry. */
 static void
 _free_link_history(void *val)
 {
@@ -113,7 +113,7 @@ _free_link_history(void *val)
   tor_free(val);
 }
 
-/** Helper: free storage held by a single OR history entry */
+/** Helper: free storage held by a single OR history entry. */
 static void
 free_or_history(void *_hist)
 {
@@ -141,8 +141,7 @@ 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)
 {
@@ -344,7 +343,8 @@ rep_hist_dump_stats(time_t now, int severity)
 }
 
 /** Remove history info for routers/links that haven't changed since
- * <b>before</b> */
+ * <b>before</b>.
+ */
 void
 rep_history_clean(time_t before)
 {
@@ -387,11 +387,10 @@ rep_history_clean(time_t before)
 #define NUM_SECS_BW_SUM_INTERVAL (15*60)
 /** How far in the past do we remember and publish bandwidth use? */
 #define NUM_SECS_BW_SUM_IS_VALID (24*60*60)
-/** How many bandwidth usage intervals do we remember? (derived.) */
+/** How many bandwidth usage intervals do we remember? (derived) */
 #define NUM_TOTALS (NUM_SECS_BW_SUM_IS_VALID/NUM_SECS_BW_SUM_INTERVAL)
 
-/**
+/** Structure to track bandwidth use, and remember the maxima for a given
- * Structure to track bandwidth use, and remember the maxima for a given
  * time period.
  */
 typedef struct bw_array_t {
@@ -423,8 +422,7 @@ typedef struct bw_array_t {
   uint64_t totals[NUM_TOTALS];
 } bw_array_t;
 
-/** Shift the current period of b forward by one.
+/** Shift the current period of b forward by one. */
- */
 static void
 commit_max(bw_array_t *b)
 {
@@ -444,8 +442,7 @@ commit_max(bw_array_t *b)
   b->total_in_period = 0;
 }
 
-/** Shift the current observation time of 'b' forward by one second.
+/** Shift the current observation time of 'b' forward by one second. */
- */
 static INLINE void
 advance_obs(bw_array_t *b)
 {
@@ -470,8 +467,7 @@ advance_obs(bw_array_t *b)
     commit_max(b);
 }
 
-/** Add 'n' bytes to the number of bytes in b for second 'when'.
+/** Add 'n' bytes to the number of bytes in b for second 'when'. */
- */
 static INLINE void
 add_obs(bw_array_t *b, time_t when, uint64_t n)
 {
@@ -488,8 +484,7 @@ add_obs(bw_array_t *b, time_t when, uint64_t n)
   b->total_in_period += n;
 }
 
-/** Allocate, initialize, and return a new bw_array.
+/** Allocate, initialize, and return a new bw_array. */
- */
 static bw_array_t *
 bw_array_new(void)
 {
@@ -506,8 +501,7 @@ bw_array_new(void)
 static bw_array_t *read_array = NULL;
 static bw_array_t *write_array = NULL;
 
-/** Set up read_array and write_array
+/** Set up read_array and write_array. */
- */
 static void
 bw_arrays_init(void)
 {
@@ -563,8 +557,7 @@ find_largest_max(bw_array_t *b)
   return max;
 }
 
-/**
+/** Find the largest sums in the past NUM_SECS_BW_SUM_IS_VALID (roughly)
- * Find the largest sums in the past NUM_SECS_BW_SUM_IS_VALID (roughly)
  * seconds. Find one sum for reading and one for writing. They don't have
  * to be at the same time).
  *
@@ -582,8 +575,7 @@ rep_hist_bandwidth_assess(void)
     return (int)(U64_TO_DBL(r)/NUM_SECS_ROLLING_MEASURE);
 }
 
-/**
+/** Print the bandwidth history of b (either read_array or write_array)
- * Print the bandwidth history of b (either read_array or write_array)
  * into the buffer pointed to by buf.  The format is simply comma
  * separated numbers, from oldest to newest.
  *
@@ -617,8 +609,7 @@ rep_hist_fill_bandwidth_history(char *buf, size_t len, bw_array_t *b)
   return cp-buf;
 }
 
-/**
+/** Allocate and return lines for representing this server's bandwidth
- * Allocate and return lines for representing this server's bandwidth
  * history in its descriptor.
  */
 char *
@@ -687,8 +678,7 @@ rep_hist_update_state(or_state_t *state)
   state->dirty = 1;
 }
 
-/** Set bandwidth history from our saved state.
+/** Set bandwidth history from our saved state. */
- */
 int
 rep_hist_load_state(or_state_t *state, char **err)
 {
@@ -756,7 +746,10 @@ static smartlist_t *predicted_ports_list=NULL;
 /** The corresponding most recently used time for each port. */
 static smartlist_t *predicted_ports_times=NULL;
 
-/** DOCDOC */
+/** We just got an application request for a connection with
+ * port <b>port</b>. Remember it for the future, so we can keep
+ * some circuits open that will exit to this port.
+ */
 static void
 add_predicted_port(uint16_t port, time_t now)
 {
@@ -770,7 +763,10 @@ add_predicted_port(uint16_t port, time_t now)
   smartlist_add(predicted_ports_times, tmp_time);
 }
 
-/** DOCDOC */
+/** Initialize whatever memory and structs are needed for predicting
+ * which ports will be used. Also seed it with port 80, so we'll build
+ * circuits on start-up.
+ */
 static void
 predicted_ports_init(void)
 {
@@ -779,7 +775,9 @@ predicted_ports_init(void)
   add_predicted_port(80, time(NULL)); /* add one to kickstart us */
 }
 
-/** DOCDOC */
+/** Free whatever memory is needed for predicting which ports will
+ * be used.
+ */
 static void
 predicted_ports_free(void)
 {