From d3af23783c35151a511fc7fc37d88cf41831448c Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Mon, 4 Nov 2019 07:40:20 -0500
Subject: [PATCH] Document our top-level directories

---
 src/app/app.dox         | 6 +++++-
 src/core/core.dox       | 6 +++++-
 src/feature/feature.dox | 7 ++++++-
 src/lib/lib.dox         | 6 +++++-
 src/tools/tools.dox     | 6 +++++-
 5 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/src/app/app.dox b/src/app/app.dox
index 8c37d9275b..29e8651d51 100644
--- a/src/app/app.dox
+++ b/src/app/app.dox
@@ -1,4 +1,8 @@
 /**
 @dir app
-@brief app
+@brief app: top-level entry point for Tor
+
+The "app" directory has Tor's main entry point and configuration logic,
+and is responsible for initializing and managing the other modules in
+Tor.
 **/
diff --git a/src/core/core.dox b/src/core/core.dox
index aacf467146..1352daebd3 100644
--- a/src/core/core.dox
+++ b/src/core/core.dox
@@ -1,4 +1,8 @@
 /**
 @dir core
-@brief core
+@brief core: main loop and onion routing functionality
+
+The "core" directory has the central protocols for Tor, which every
+client and relay must implement in order to perform onion routing.
+
 **/
diff --git a/src/feature/feature.dox b/src/feature/feature.dox
index 880a262a0d..1d9c3a9df4 100644
--- a/src/feature/feature.dox
+++ b/src/feature/feature.dox
@@ -1,4 +1,9 @@
 /**
 @dir feature
-@brief feature
+@brief feature: domain-specific modules
+
+The "feature" directory has modules that Tor uses only for a particular
+role or service, such as maintaining/using an onion service, operating as a
+relay or a client, or being a directory authority.
+
 **/
diff --git a/src/lib/lib.dox b/src/lib/lib.dox
index 28d4c52c66..f1b2291c76 100644
--- a/src/lib/lib.dox
+++ b/src/lib/lib.dox
@@ -1,4 +1,8 @@
 /**
 @dir lib
-@brief lib
+@brief lib: low-level functionality.
+
+The "lib" directory contains low-level functionality, most of it not
+necessarily Tor-specific.
+
 **/
diff --git a/src/tools/tools.dox b/src/tools/tools.dox
index 9f73d1c9a0..54aa4df48e 100644
--- a/src/tools/tools.dox
+++ b/src/tools/tools.dox
@@ -1,4 +1,8 @@
 /**
 @dir tools
-@brief tools
+@brief tools: other command-line tools for use with Tor.
+
+The "tools" directory has a few other programs that use Tor, but are not part
+of the main Tor binary.
+
 **/