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, 12 insertions, 0 deletions

diff --git a/src/or/keypin.c b/src/or/keypin.c
index 335c793cd9..2d4c4e92d2 100644
--- a/src/or/keypin.c
+++ b/src/or/keypin.c
@@ -39,16 +39,28 @@
  * @brief Key-pinning for RSA and Ed25519 identity keys at directory
  *  authorities.
  *
+ * Many older clients, and many internal interfaces, still refer to relays by
+ * their RSA1024 identity keys.  We can make this more secure, however:
+ * authorities use this module to track which RSA keys have been used along
+ * with which Ed25519 keys, and force such associations to be permanent.
+ *
  * This module implements a key-pinning mechanism to ensure that it's safe
  * to use RSA keys as identitifers even as we migrate to Ed25519 keys.  It
  * remembers, for every Ed25519 key we've seen, what the associated Ed25519
  * key is.  This way, if we see a different Ed25519 key with that RSA key,
  * we'll know that there's a mismatch.
  *
+ * (As of this writing, these key associations are advisory only, mostly
+ * because some relay operators kept mishandling their Ed25519 keys during
+ * the initial Ed25519 rollout.  We should fix this problem, and then toggle
+ * the AuthDirPinKeys option.)
+ *
  * We persist these entries to disk using a simple format, where each line
  * has a base64-encoded RSA SHA1 hash, then a base64-endoded Ed25519 key.
  * Empty lines, misformed lines, and lines beginning with # are
  * ignored. Lines beginning with @ are reserved for future extensions.
+ *
+ * The dirserv.c module is the main user of these functions.
  */
 
 static int keypin_journal_append_entry(const uint8_t *rsa_id_digest,