Merge branch 'doxygen_libs'

17 files changed, 104 insertions, 33 deletions

diff --git a/src/feature/api/feature_api.dox b/src/feature/api/feature_api.dox
index cb723b0601..06112120c3 100644
--- a/src/feature/api/feature_api.dox
+++ b/src/feature/api/feature_api.dox
@@ -1,4 +1,4 @@
 /**
-@dir feature/api
-@brief feature/api
+@dir /feature/api
+@brief feature/api: In-process interface to starting/stopping Tor.
 **/
diff --git a/src/feature/client/feature_client.dox b/src/feature/client/feature_client.dox
index 1a4881c50a..a8263b494c 100644
--- a/src/feature/client/feature_client.dox
+++ b/src/feature/client/feature_client.dox
@@ -1,4 +1,7 @@
 /**
-@dir feature/client
-@brief feature/client
+@dir /feature/client
+@brief feature/client: Client-specific code
+
+(There is also a bunch of client-specific code in other modules.)
+
 **/
diff --git a/src/feature/control/feature_control.dox b/src/feature/control/feature_control.dox
index 1f6e83c1dd..a0bf9413a1 100644
--- a/src/feature/control/feature_control.dox
+++ b/src/feature/control/feature_control.dox
@@ -1,4 +1,10 @@
 /**
-@dir feature/control
-@brief feature/control
+@dir /feature/control
+@brief feature/control: Controller API.
+
+The Controller API is a text-based protocol that another program (or another
+thread, if you're running Tor in-process) can use to configure and control
+Tor while it is running.  The current protocol is documented in
+[control-spec.txt](https://gitweb.torproject.org/torspec.git/tree/control-spec.txt).
+
 **/
diff --git a/src/feature/dirauth/feature_dirauth.dox b/src/feature/dirauth/feature_dirauth.dox
index fa4bee5b31..9ee2d04589 100644
--- a/src/feature/dirauth/feature_dirauth.dox
+++ b/src/feature/dirauth/feature_dirauth.dox
@@ -1,4 +1,11 @@
 /**
-@dir feature/dirauth
-@brief feature/dirauth
+@dir /feature/dirauth
+@brief feature/dirauth: Directory authority implementation.
+
+This module handles running Tor as a directory authority.
+
+The directory protocol is specified in
+[dir-spec.txt](https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt).
+
+
 **/
diff --git a/src/feature/dircache/feature_dircache.dox b/src/feature/dircache/feature_dircache.dox
index 5f1c5cc70f..ef8a51aa9e 100644
--- a/src/feature/dircache/feature_dircache.dox
+++ b/src/feature/dircache/feature_dircache.dox
@@ -1,4 +1,8 @@
 /**
-@dir feature/dircache
-@brief feature/dircache
+@dir /feature/dircache
+@brief feature/dircache: Run as a directory cache server
+
+This module handles the directory caching functionality that all relays may
+provide, for serving cached directory objects to objects.
+
 **/
diff --git a/src/feature/dirclient/feature_dirclient.dox b/src/feature/dirclient/feature_dirclient.dox
index 984a17cf51..0cbae69111 100644
--- a/src/feature/dirclient/feature_dirclient.dox
+++ b/src/feature/dirclient/feature_dirclient.dox
@@ -1,4 +1,9 @@
 /**
-@dir feature/dirclient
-@brief feature/dirclient
+@dir /feature/dirclient
+@brief feature/dirclient: Directory client implementation.
+
+The code here is used by all Tor instances that need to download directory
+information.  Currently, that is all of them, since even authorities need to
+launch downloads to learn about relays that other authorities have listed.
+
 **/
diff --git a/src/feature/dircommon/feature_dircommon.dox b/src/feature/dircommon/feature_dircommon.dox
index 2eff21065c..2d9866da01 100644
--- a/src/feature/dircommon/feature_dircommon.dox
+++ b/src/feature/dircommon/feature_dircommon.dox
@@ -1,4 +1,9 @@
 /**
-@dir feature/dircommon
-@brief feature/dircommon
+@dir /feature/dircommon
+@brief feature/dircommon: Directory client and server shared code
+
+This module has the code that directory clients (anybody who download
+information about relays) and directory servers (anybody who serves such
+information) share in common.
+
 **/
diff --git a/src/feature/dirparse/feature_dirparse.dox b/src/feature/dirparse/feature_dirparse.dox
index a6b34c1f5f..4f2136b02b 100644
--- a/src/feature/dirparse/feature_dirparse.dox
+++ b/src/feature/dirparse/feature_dirparse.dox
@@ -1,4 +1,10 @@
 /**
-@dir feature/dirparse
-@brief feature/dirparse
+@dir /feature/dirparse
+@brief feature/dirparse: Parsing Tor directory objects
+
+We define a number of "directory objects" in
+[dir-spec.txt](https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt),
+all of them using a common line-oriented meta-format.  This module is used by
+other parts of Tor to parse them.
+
 **/
diff --git a/src/feature/feature.dox b/src/feature/feature.dox
index 1d9c3a9df4..03759f9a17 100644
--- a/src/feature/feature.dox
+++ b/src/feature/feature.dox
@@ -1,5 +1,5 @@
 /**
-@dir feature
+@dir /feature
 @brief feature: domain-specific modules
 
 The "feature" directory has modules that Tor uses only for a particular
diff --git a/src/feature/hibernate/feature_hibernate.dox b/src/feature/hibernate/feature_hibernate.dox
index e24620a43c..eebb2d51a2 100644
--- a/src/feature/hibernate/feature_hibernate.dox
+++ b/src/feature/hibernate/feature_hibernate.dox
@@ -1,4 +1,16 @@
 /**
-@dir feature/hibernate
-@brief feature/hibernate
+@dir /feature/hibernate
+@brief feature/hibernate: Bandwidth accounting and hibernation (!)
+
+This module implements two features that are only somewhat related, and
+should probably be separated in the future.  One feature is bandwidth
+accounting (making sure we use no more than so many gigabytes in a day) and
+hibernation (avoiding network activity while we have used up all/most of our
+configured gigabytes).  The other feature is clean shutdown, where we stop
+accepting new connections for a while and give the old ones time to close.
+
+The two features are related only in the sense that "soft hibernation" (being
+almost out of ) is very close to the "shutting down" state.  But it would be
+better in the long run to make the two completely separate.
+
 **/
diff --git a/src/feature/hs/feature_hs.dox b/src/feature/hs/feature_hs.dox
index 08801d002d..32f44d57fb 100644
--- a/src/feature/hs/feature_hs.dox
+++ b/src/feature/hs/feature_hs.dox
@@ -1,4 +1,10 @@
 /**
-@dir feature/hs
-@brief feature/hs
+@dir /feature/hs
+@brief feature/hs: v3 (current) onion service protocol
+
+This directory implements the v3 onion service protocol,
+as specified in
+[rend-spec-v3.txt](https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt).
+
+
 **/
diff --git a/src/feature/hs_common/feature_hs_common.dox b/src/feature/hs_common/feature_hs_common.dox
index 8fd4f1b07c..85d7585872 100644
--- a/src/feature/hs_common/feature_hs_common.dox
+++ b/src/feature/hs_common/feature_hs_common.dox
@@ -1,4 +1,5 @@
 /**
-@dir feature/hs_common
-@brief feature/hs_common
+@dir /feature/hs_common
+@brief feature/hs_common: Common to v2 (old) and v3 (current) onion services
+
 **/
diff --git a/src/feature/keymgt/feature_keymgt.dox b/src/feature/keymgt/feature_keymgt.dox
index 8f72c70bbd..acc840eb2e 100644
--- a/src/feature/keymgt/feature_keymgt.dox
+++ b/src/feature/keymgt/feature_keymgt.dox
@@ -1,4 +1,5 @@
 /**
-@dir feature/keymgt
-@brief feature/keymgt
+@dir /feature/keymgt
+@brief feature/keymgt: Store keys for relays, authorities, etc.
+
 **/
diff --git a/src/feature/nodelist/feature_nodelist.dox b/src/feature/nodelist/feature_nodelist.dox
index faeb9970b3..0b25dd246d 100644
--- a/src/feature/nodelist/feature_nodelist.dox
+++ b/src/feature/nodelist/feature_nodelist.dox
@@ -1,4 +1,4 @@
 /**
-@dir feature/nodelist
-@brief feature/nodelist
+@dir /feature/nodelist
+@brief feature/nodelist: Download and manage a list of relays
 **/
diff --git a/src/feature/relay/feature_relay.dox b/src/feature/relay/feature_relay.dox
index 9aa7af48e6..6867818257 100644
--- a/src/feature/relay/feature_relay.dox
+++ b/src/feature/relay/feature_relay.dox
@@ -1,4 +1,6 @@
 /**
-@dir feature/relay
-@brief feature/relay
+@dir /feature/relay
+@brief feature/relay: Relay-specific code
+
+(There is also a bunch of relay-specific code in other modules.)
 **/
diff --git a/src/feature/rend/feature_rend.dox b/src/feature/rend/feature_rend.dox
index fcba0d460f..ed0784521c 100644
--- a/src/feature/rend/feature_rend.dox
+++ b/src/feature/rend/feature_rend.dox
@@ -1,4 +1,9 @@
 /**
-@dir feature/rend
-@brief feature/rend
+@dir /feature/rend
+@brief feature/rend: version 2 (old) hidden services
+
+This directory implements the v2 onion service protocol,
+as specified in
+[rend-spec-v2.txt](https://gitweb.torproject.org/torspec.git/tree/rend-spec-v2.txt).
+
 **/
diff --git a/src/feature/stats/feature_stats.dox b/src/feature/stats/feature_stats.dox
index fc4ffd19df..0ced00ce58 100644
--- a/src/feature/stats/feature_stats.dox
+++ b/src/feature/stats/feature_stats.dox
@@ -1,4 +1,12 @@
 /**
-@dir feature/stats
-@brief feature/stats
+@dir /feature/stats
+@brief feature/stats: Relay statistics. Also, port prediction.
+
+This module collects anonymized relay statistics in order to publish them in
+relays' routerinfo and extrainfo documents.
+
+Additionally, it contains predict_ports.c, which remembers which ports we've
+visited recently as a client, so we can make sure we have open circuits that
+support them.
+
 **/