commit fe6ca826dfc4d107faead4d3293740f29ad88ac1 Author: Nick Mathewson <nickm@torproject.org> Date: Sat Feb 27 18:08:24 2016 +0100 Make sure that every module in src/or has a brief description. --- src/or/addressmap.c | 9 +++++++++ src/or/buffers.c | 3 ++- src/or/channel.c | 6 +++++- src/or/channeltls.c | 4 +++- src/or/circpathbias.c | 9 +++++++++ src/or/circuitbuild.c | 4 +++- src/or/circuitlist.c | 3 ++- src/or/circuitstats.c | 7 +++++++ src/or/confparse.c | 7 +++++++ src/or/dnsserv.c | 3 ++- src/or/fp_pair.c | 8 ++++++++ src/or/keypin.c | 7 +++++++ src/or/microdesc.c | 7 +++++++ src/or/nodelist.c | 8 ++++++++ src/or/ntmain.c | 6 ++++++ src/or/onion_ntor.c | 6 ++++++ src/or/periodic.c | 6 ++++++ src/or/routerkeys.c | 8 ++++++++ src/or/routerset.c | 7 +++++++ src/or/statefile.c | 7 +++++++ src/or/torcert.c | 7 +++++++ 21 files changed, 126 insertions(+), 6 deletions(-) diff --git a/src/or/addressmap.c b/src/or/addressmap.c index 9c29fb2..26b062f 100644 --- a/src/or/addressmap.c +++ b/src/or/addressmap.c @@ -4,6 +4,15 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file addressmap.c + * + * \brief The addressmap module manages the processes by which we rewrite + * addresses in client requess. It handles the MapAddress controller and + * torrc commands, and the TrackHostExits feature, and the client-side DNS + * cache (deprecated). + */ + #define ADDRESSMAP_PRIVATE #include "or.h" diff --git a/src/or/buffers.c b/src/or/buffers.c index cdb499b..9bd0cba 100644 --- a/src/or/buffers.c +++ b/src/or/buffers.c @@ -8,7 +8,8 @@ * \file buffers.c * \brief Implements a generic interface buffer. Buffers are * fairly opaque string holders that can read to or flush from: - * memory, file descriptors, or TLS connections. + * memory, file descriptors, or TLS connections. Buffers are implemented + * as linked lists of memory chunks. **/ #define BUFFERS_PRIVATE #include "or.h" diff --git a/src/or/channel.c b/src/or/channel.c index 46e8338..45ff501 100644 --- a/src/or/channel.c +++ b/src/or/channel.c @@ -3,7 +3,11 @@ /** * \file channel.c - * \brief OR-to-OR channel abstraction layer + * + * \brief OR/OP-to-OR channel abstraction layer. A channel's job is to + * transfer cells from Tor instance to Tor instance. + * Currently, there is only one implementation of the channel abstraction: in + * channeltls.c. **/ /* diff --git a/src/or/channeltls.c b/src/or/channeltls.c index 016ef75..67e6d40 100644 --- a/src/or/channeltls.c +++ b/src/or/channeltls.c @@ -3,7 +3,9 @@ /** * \file channeltls.c - * \brief channel_t concrete subclass using or_connection_t + * + * \brief A concrete subclass of channel_t using or_connection_t to transfer + * cells between Tor instances. **/ /* diff --git a/src/or/circpathbias.c b/src/or/circpathbias.c index a0115cc..5c8849f 100644 --- a/src/or/circpathbias.c +++ b/src/or/circpathbias.c @@ -4,6 +4,15 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file circpathbias.c + * + * \brief Code to track success/failure rates of circuits built through + * different tor nodes, in an attempt to detect attacks where + * an attacker deliberately causes circuits to fail until the client + * choses a path they like. + */ + #include "or.h" #include "channel.h" #include "circpathbias.h" diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c index daf0b2a..69c34b5 100644 --- a/src/or/circuitbuild.c +++ b/src/or/circuitbuild.c @@ -6,7 +6,9 @@ /** * \file circuitbuild.c - * \brief The actual details of building circuits. + * + * \brief Implements the details of building circuits (by chosing paths, + * constructing/sending create/extend cells, and so on). **/ #define CIRCUITBUILD_PRIVATE diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c index ade371d..61d2bb8 100644 --- a/src/or/circuitlist.c +++ b/src/or/circuitlist.c @@ -6,7 +6,8 @@ /** * \file circuitlist.c - * \brief Manage the global circuit list. + * + * \brief Manage the global circuit list, and looking up circuits within it. **/ #define CIRCUITLIST_PRIVATE #include "or.h" diff --git a/src/or/circuitstats.c b/src/or/circuitstats.c index 3ced5af..7449244 100644 --- a/src/or/circuitstats.c +++ b/src/or/circuitstats.c @@ -4,6 +4,13 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file circuitstats.c + * + * \brief Maintains and analyzes statistics about circuit built times, so we + * can tell how long we may need to wait for a fast circuit to be constructed. + */ + #define CIRCUITSTATS_PRIVATE #include "or.h" diff --git a/src/or/confparse.c b/src/or/confparse.c index ac21df2..26909c8 100644 --- a/src/or/confparse.c +++ b/src/or/confparse.c @@ -4,6 +4,13 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file confparse.c + * + * \brief Back-end for parsing and generating key-value files, used to + * implement the torrc file format and the state file. + */ + #include "or.h" #include "confparse.h" #include "routerset.h" diff --git a/src/or/dnsserv.c b/src/or/dnsserv.c index ded0d84..941b9e2 100644 --- a/src/or/dnsserv.c +++ b/src/or/dnsserv.c @@ -2,7 +2,8 @@ /* See LICENSE for licensing information */ /** - * \file dnsserv.c \brief Implements client-side DNS proxy server code. Note: + * \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. diff --git a/src/or/fp_pair.c b/src/or/fp_pair.c index c863d41..a1924fe 100644 --- a/src/or/fp_pair.c +++ b/src/or/fp_pair.c @@ -1,6 +1,14 @@ /* Copyright (c) 2013-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file fp_pair.c + * + * \brief Manages data structures for associating pairs of fingerprints. Used + * to handle combinations of identity/signing-key fingerprints for + * authorities. + **/ + #include "or.h" #include "fp_pair.h" diff --git a/src/or/keypin.c b/src/or/keypin.c index 574a76d..6c294c7 100644 --- a/src/or/keypin.c +++ b/src/or/keypin.c @@ -1,6 +1,13 @@ /* Copyright (c) 2014, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file keypin.c + * + * \brief Functions and structures for associating routers' RSA key + * fingerprints with their ED25519 keys. + */ + #define KEYPIN_PRIVATE #include "orconfig.h" diff --git a/src/or/microdesc.c b/src/or/microdesc.c index 900a50e..520cade 100644 --- a/src/or/microdesc.c +++ b/src/or/microdesc.c @@ -1,6 +1,13 @@ /* Copyright (c) 2009-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file microdesc.c + * + * \brief Implements microdescriptors -- an abbreviated description of + * less-frequently-changing router information. + */ + #include "or.h" #include "circuitbuild.h" #include "config.h" diff --git a/src/or/nodelist.c b/src/or/nodelist.c index 91353ee..2fbcabb 100644 --- a/src/or/nodelist.c +++ b/src/or/nodelist.c @@ -4,6 +4,14 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file nodelist.c + * + * \brief Structures and functions for tracking what we know about the routers + * on the Tor network, and correlating information from networkstatus, + * routerinfo, and microdescs. + */ + #include "or.h" #include "address.h" #include "config.h" diff --git a/src/or/ntmain.c b/src/or/ntmain.c index b31ed86..89739ad 100644 --- a/src/or/ntmain.c +++ b/src/or/ntmain.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ntmain.c + * + * \brief Entry points for running/configuring Tor as Windows Service. + */ + #ifdef _WIN32 #include "or.h" diff --git a/src/or/onion_ntor.c b/src/or/onion_ntor.c index 539f06f..c394096 100644 --- a/src/or/onion_ntor.c +++ b/src/or/onion_ntor.c @@ -1,6 +1,12 @@ /* Copyright (c) 2012-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file onion_ntor.c + * + * \brief Implementation for the ntor handshake. + */ + #include "orconfig.h" #define ONION_NTOR_PRIVATE diff --git a/src/or/periodic.c b/src/or/periodic.c index 109717f..2f819e9 100644 --- a/src/or/periodic.c +++ b/src/or/periodic.c @@ -1,6 +1,12 @@ /* Copyright (c) 2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file periodic.c + * + * \brief Generic backend for handling periodic events. + */ + #include "or.h" #include "compat_libevent.h" #include "config.h" diff --git a/src/or/routerkeys.c b/src/or/routerkeys.c index 210178d..9d3a9c3 100644 --- a/src/or/routerkeys.c +++ b/src/or/routerkeys.c @@ -1,6 +1,14 @@ /* Copyright (c) 2014, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \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.) + */ + #include "or.h" #include "config.h" #include "router.h" diff --git a/src/or/routerset.c b/src/or/routerset.c index debe9ec..073e762 100644 --- a/src/or/routerset.c +++ b/src/or/routerset.c @@ -4,6 +4,13 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file routerset.c + * + * \brief Functions and structures to handle set-type selection of routers + * by name, ID, address, etc. + */ + #define ROUTERSET_PRIVATE #include "or.h" diff --git a/src/or/statefile.c b/src/or/statefile.c index 7fe8dc5..12cef12 100644 --- a/src/or/statefile.c +++ b/src/or/statefile.c @@ -4,6 +4,13 @@ * Copyright (c) 2007-2015, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file statefile.c + * + * \brief Handles parsing and encoding the persistent 'state' file that carries + * miscellaneous persistent state between Tor invocations. + */ + #define STATEFILE_PRIVATE #include "or.h" #include "circuitstats.h" diff --git a/src/or/torcert.c b/src/or/torcert.c index ef5b4c0..9c02f9c 100644 --- a/src/or/torcert.c +++ b/src/or/torcert.c @@ -1,6 +1,13 @@ /* Copyright (c) 2014, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file torcert.c + * + * \brief Implementation for ed25519-signed certificates as used in the Tor + * protocol. + */ + #include "crypto.h" #include "torcert.h" #include "ed25519_cert.h"