[tor-commits] [tor/master] Module-document dnsserv.c, policies.c, routerkeys.c

[nickm at torproject.org]

commit 961c8f4838d36565ef7a54df1ed2cd692db93430
Author: Nick Mathewson <nickm at torproject.org>
Date:   Mon Oct 24 11:47:40 2016 -0400

    Module-document dnsserv.c, policies.c, routerkeys.c
---
 src/or/dnsserv.c    | 20 ++++++++++++++++----
 src/or/policies.c   |  7 +++++++
 src/or/routerkeys.c |  9 +++++++--
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/src/or/dnsserv.c b/src/or/dnsserv.c
index 04be3e8..8dce832 100644
--- a/src/or/dnsserv.c
+++ b/src/or/dnsserv.c
@@ -3,10 +3,22 @@
 
 /**
  * \file dnsserv.c
- * \brief Implements client-side DNS proxy server code.  Note:
- * 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
- * other hand, runs on Tor servers, and acts as a DNS client.
+ * \brief Implements client-side DNS proxy server code.
+ *
+ * When a user enables the DNSPort configuration option to have their local
+ * 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"
diff --git a/src/or/policies.c b/src/or/policies.c
index 44a46d2..4b26c69 100644
--- a/src/or/policies.c
+++ b/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
diff --git a/src/or/routerkeys.c b/src/or/routerkeys.c
index ca32228..7a1a2c9 100644
--- a/src/or/routerkeys.c
+++ b/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
- *  belongs here.)
+ *  set of keypairs necessary to be an OR.
+ *
+ * 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"