Module-document dnsserv.c, policies.c, routerkeys.c

src/or/dnsserv.c

@@ -3,10 +3,22 @@
 
 /**
  * \file dnsserv.c
- * \brief Implements client-side DNS proxy server code.  Note:
+ * \brief Implements client-side DNS proxy server code.
- * this is the DNS Server code, not the Server DNS code.  Confused?  This code
+ *
- * runs on client-side, and acts as a DNS server.  The code in dns.c, on the
+ * When a user enables the DNSPort configuration option to have their local
- * other hand, runs on Tor servers, and acts as a DNS client.
+ * Tor client handle DNS requests, this module handles it.  It functions as a
+ * "DNS Server" on the client side, which client applications use.
+ *
+ * Inbound DNS requests are represented as entry_connection_t here (since
+ * that's how Tor represents client-side streams), which are kept associated
+ * with an evdns_server_request structure as exposed by Libevent's
+ * evdns code.
+ *
+ * Upon receiving a DNS request, libevent calls our evdns_server_callback()
+ * function here, which causes this module to create an entry_connection_t
+ * request as appropriate.  Later, when that request is answered,
+ * connection_edge.c calls dnsserv_resolved() so we can finish up and tell the
+ * DNS client.
  **/
 
 #include "or.h"

src/or/policies.c

@@ -6,6 +6,13 @@
 /**
  * \file policies.c
  * \brief Code to parse and use address policies and exit policies.
+ *
+ * We have two key kinds of address policy: full and compressed.  A full
+ * policy is an array of accept/reject patterns, to be applied in order.
+ * A short policy is simply a list of ports.  This module handles both
+ * kinds, including generic functions to apply them to addresses, and
+ * also including code to manage the global policies that we apply to
+ * incoming and outgoing connections.
  **/
 
 #define POLICIES_PRIVATE

src/or/routerkeys.c

@@ -5,8 +5,13 @@
  * \file routerkeys.c
  *
  * \brief Functions and structures to handle generating and maintaining the
- *  set of keypairs necessary to be an OR. (Some of the code in router.c
+ *  set of keypairs necessary to be an OR.
- *  belongs here.)
+ *
+ * The keys handled here now are the Ed25519 keys that Tor relays use to sign
+ * descriptors, authenticate themselves on links, and identify one another
+ * uniquely.  Other keys are maintained in router.c and rendservice.c.
+ *
+ * (TODO: The keys in router.c should go here too.)
  */
 
 #include "or.h"