Write a bunch of module documentation.

This commit adds or improves the module-level documenation for:

  buffers.c circuitstats.c command.c connection_edge.c control.c
  cpuworker.c crypto_curve25519.c crypto_curve25519.h
  crypto_ed25519.c crypto_format.c dircollate.c dirserv.c dns.c
  dns_structs.h fp_pair.c geoip.c hibernate.c keypin.c ntmain.c
  onion.c onion_fast.c onion_ntor.c onion_tap.c periodic.c
  protover.c protover.h reasons.c rephist.c replaycache.c
  routerlist.c routerparse.c routerset.c statefile.c status.c
  tor_main.c workqueue.c

In particular, I've tried to explain (for each documented module)
what each module does, what's in it, what the big idea is, why it
belongs in Tor, and who calls it.  In a few cases, I've added TODO
notes about refactoring opportunities.

I've also renamed an argument, and fixed a few DOCDOC comments.

1 files changed, 18 insertions, 6 deletions

diff --git a/src/or/hibernate.c b/src/or/hibernate.c
index 7e25306234..aaf5c4bdcd 100644
--- a/src/or/hibernate.c
+++ b/src/or/hibernate.c
@@ -8,6 +8,12 @@
  * etc in preparation for closing down or going dormant; and to track
  * bandwidth and time intervals to know when to hibernate and when to
  * stop hibernating.
+ *
+ * Ordinarily a Tor relay is "Live".
+ *
+ * A live relay can stop accepting connections for one of two reasons: either
+ * it is trying to conserve bandwidth because of bandwidth accounting rules
+ * ("soft hibernation"), or it is about to shut down ("exiting").
  **/
 
 /*
@@ -49,8 +55,10 @@ typedef enum {
   UNIT_MONTH=1, UNIT_WEEK=2, UNIT_DAY=3,
 } time_unit_t;
 
-/* Fields for accounting logic.  Accounting overview:
+/*
+ * @file hibernate.c
  *
+ * <h4>Accounting</h4>
  * Accounting is designed to ensure that no more than N bytes are sent in
  * either direction over a given interval (currently, one month, one week, or
  * one day) We could
@@ -64,17 +72,21 @@ typedef enum {
  *
  * Each interval runs as follows:
  *
- * 1. We guess our bandwidth usage, based on how much we used
+ * <ol>
+ * <li>We guess our bandwidth usage, based on how much we used
  *     last time.  We choose a "wakeup time" within the interval to come up.
- * 2. Until the chosen wakeup time, we hibernate.
- * 3. We come up at the wakeup time, and provide bandwidth until we are
+ * <li>Until the chosen wakeup time, we hibernate.
+ * <li> We come up at the wakeup time, and provide bandwidth until we are
  *    "very close" to running out.
- * 4. Then we go into low-bandwidth mode, and stop accepting new
+ * <li> Then we go into low-bandwidth mode, and stop accepting new
  *    connections, but provide bandwidth until we run out.
- * 5. Then we hibernate until the end of the interval.
+ * <li> Then we hibernate until the end of the interval.
  *
  * If the interval ends before we run out of bandwidth, we go back to
  * step one.
+ *
+ * Accounting is controlled by the AccountingMax, AccountingRule, and
+ * AccountingStart options.
  */
 
 /** How many bytes have we read in this accounting interval? */