22 files changed, 120 insertions, 52 deletions
diff --git a/src/lib/buf/lib_buf.dox b/src/lib/buf/lib_buf.dox
index 9caaba07f0..a2ac23ee4c 100644
--- a/src/lib/buf/lib_buf.dox
+++ b/src/lib/buf/lib_buf.dox
@@ -1,4 +1,15 @@
 /**
 @dir /lib/buf
-@brief lib/buf
+@brief lib/buf: An efficient byte queue.
+
+This module defines the buf_t type, which is used throughout our networking
+code.  The implementation is a singly-linked queue of buffer chunks, similar
+to the BSD kernel's
+["mbuf"](https://www.freebsd.org/cgi/man.cgi?query=mbuf&sektion=9) structure.
+
+The buf_t type is also reasonable for use in constructing long strings.
+
+See \refdir{lib/net} for networking code that uses buf_t, and
+\refdir{lib/tls} for cryptographic code that uses buf_t.
+
 **/
diff --git a/src/lib/compress/lib_compress.dox b/src/lib/compress/lib_compress.dox
index b1b0902359..599126901a 100644
--- a/src/lib/compress/lib_compress.dox
+++ b/src/lib/compress/lib_compress.dox
@@ -1,4 +1,8 @@
 /**
 @dir /lib/compress
-@brief lib/compress
+@brief lib/compress: Wraps several compression libraries
+
+Currently supported are zlib (mandatory), zstd (optional), and lzma
+(optional).
+
 **/
diff --git a/src/lib/confmgt/lib_confmgt.dox b/src/lib/confmgt/lib_confmgt.dox
index 86cb04e847..d18fa304ca 100644
--- a/src/lib/confmgt/lib_confmgt.dox
+++ b/src/lib/confmgt/lib_confmgt.dox
@@ -1,4 +1,9 @@
 /**
 @dir /lib/confmgt
-@brief lib/confmgt
+@brief lib/confmgt: Parse, encode, manipulate configuration files.
+
+This logic is used in common by our state files (statefile.c) and
+configuration files (config.c) to manage a set of named, typed fields,
+reading and writing them to disk and to the controller.
+
 **/
diff --git a/src/lib/crypt_ops/lib_crypt_ops.dox b/src/lib/crypt_ops/lib_crypt_ops.dox
index 0c3e4d7c3f..d856d93be1 100644
--- a/src/lib/crypt_ops/lib_crypt_ops.dox
+++ b/src/lib/crypt_ops/lib_crypt_ops.dox
@@ -1,4 +1,12 @@
 /**
 @dir /lib/crypt_ops
-@brief lib/crypt_ops
+@brief lib/crypt_ops: Cryptographic operations.
+
+This module contains wrappers around the cryptographic libraries that we
+support, and implementations for some higher-level cryptographic
+constructions that we use.
+
+It wraps our two major cryptographic backends (OpenSSL or NSS, as configured
+by the user), and also wraps other cryptographic code in src/ext.
+
 **/
diff --git a/src/lib/evloop/lib_evloop.dox b/src/lib/evloop/lib_evloop.dox
index f60f41968c..52fcf67755 100644
--- a/src/lib/evloop/lib_evloop.dox
+++ b/src/lib/evloop/lib_evloop.dox
@@ -1,4 +1,9 @@
 /**
 @dir /lib/evloop
-@brief lib/evloop
+@brief lib/evloop: Low-level event loop.
+
+This modules has tools to manage the [libevent](https://libevent.org/) event
+loop and related functionality, in order to implement asynchronous
+networking, timers, periodic events, and other scheduling tasks.
+
 **/
diff --git a/src/lib/fdio/lib_fdio.dox b/src/lib/fdio/lib_fdio.dox
index 2615b9791e..9e2fda617a 100644
--- a/src/lib/fdio/lib_fdio.dox
+++ b/src/lib/fdio/lib_fdio.dox
@@ -1,6 +1,6 @@
 /**
 @dir /lib/fdio
-@brief lib/fdio Code to read/write on file descriptors.
+@brief lib/fdio: Code to read/write on file descriptors.
 
 (This module also handles sockets, on platforms where a socket is not a kind
 of fd.)
diff --git a/src/lib/fs/lib_fs.dox b/src/lib/fs/lib_fs.dox
index 33ff169280..4466250bb8 100644
--- a/src/lib/fs/lib_fs.dox
+++ b/src/lib/fs/lib_fs.dox
@@ -1,4 +1,11 @@
 /**
 @dir /lib/fs
-@brief lib/fs
+@brief lib/fs: Files, filenames, directories, etc.
+
+This module is mostly a set of compatibility wrappers around
+operating-system-specific filesystem access.
+
+It also contains a set of convenience functions for safely writing to files,
+creating directories, and so on.
+
 **/
diff --git a/src/lib/geoip/lib_geoip.dox b/src/lib/geoip/lib_geoip.dox
index 454dcb6874..da1123640b 100644
--- a/src/lib/geoip/lib_geoip.dox
+++ b/src/lib/geoip/lib_geoip.dox
@@ -1,4 +1,5 @@
 /**
 @dir /lib/geoip
-@brief lib/geoip
+@brief lib/geoip: IP-to-country mapping
+
 **/
diff --git a/src/lib/intmath/lib_intmath.dox b/src/lib/intmath/lib_intmath.dox
index 33fa0f02b6..e9b7044706 100644
--- a/src/lib/intmath/lib_intmath.dox
+++ b/src/lib/intmath/lib_intmath.dox
@@ -1,4 +1,4 @@
 /**
 @dir /lib/intmath
-@brief lib/intmath Integer mathematics.
+@brief lib/intmath: Integer mathematics.
 **/
diff --git a/src/lib/lib.dox b/src/lib/lib.dox
index da6f7b2d2e..fdf2c47687 100644
--- a/src/lib/lib.dox
+++ b/src/lib/lib.dox
@@ -69,10 +69,7 @@ level):
    - \refdir{lib/trace} -- A general-purpose API
      function-tracing functionality Tor.  (_Currently not much used._)
 
-   - \refdir{lib/thread} -- Threading compatibility and utility
-     functionality, other than low-level locks (which are in
-     \refdir{lib/lock} and workqueue/threadpool code (which belongs
-     in \refdir{lib/evloop}.)
+   - \refdir{lib/thread} -- Mid-level Threading.
 
    - \refdir{lib/term} -- Terminal manipulation
      (like reading a password from the user).
@@ -89,19 +86,13 @@ level):
    - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox
      implementation.
 
-   - \refdir{lib/pubsub} -- Code and macros to implement our
-     publish/subscribe message passing system.
+   - \refdir{lib/pubsub} -- A publish/subscribe message passing system.
 
-   - \refdir{lib/fs} -- Utility and compatibility code for
-     manipulating files, filenames, directories, and so on.
+   - \refdir{lib/fs} -- Files, filenames, directories, etc.
 
-   - \refdir{lib/confmgt} -- Code to parse, encode, and
-     manipulate our configuration files, state files, and so forth.
+   - \refdir{lib/confmgt} -- Parse, encode, and manipulate onfiguration files.
 
-   - \refdir{lib/crypt_ops} -- Cryptographic operations. This
-     module contains wrappers around the cryptographic libraries that we
-     support, and implementations for some higher-level cryptographic
-     constructions that we use.
+   - \refdir{lib/crypt_ops} -- Cryptographic operations.
 
    - \refdir{lib/meminfo} -- Functions for inspecting our
      memory usage, if the malloc implementation exposes that to us.
@@ -109,31 +100,22 @@ level):
    - \refdir{lib/time} -- Higher level time functions, including
      fine-gained and monotonic timers.
 
-   - \refdir{lib/math} -- Floating-point mathematical utilities,
-     including compatibility code, and probability distributions.
+   - \refdir{lib/math} -- Floating-point mathematical utilities.
 
-   - \refdir{lib/buf} -- A general purpose queued buffer
-     implementation, similar to the BSD kernel's "mbuf" structure.
+   - \refdir{lib/buf} -- An efficient byte queue.
 
    - \refdir{lib/net} -- Networking code, including address
-     manipulation, compatibility wrappers,
+     manipulation, compatibility wrappers, etc.
 
-   - \refdir{lib/compress} -- A compatibility wrapper around
-     several compression libraries, currently including zlib, zstd, and lzma.
+   - \refdir{lib/compress} -- Wraps several compression libraries.
 
-   - \refdir{lib/geoip} -- Utilities to manage geoip (IP to
-      country) lookups and formats.
+   - \refdir{lib/geoip} -- IP-to-country mapping.
 
-   - \refdir{lib/tls} -- Compatibility wrappers around the library
-     (NSS or OpenSSL, depending on configuration) that Tor uses to implement
-     the TLS link security protocol.
+   - \refdir{lib/tls} -- TLS library wrappers.
 
-   - \refdir{lib/evloop} -- Tools to manage the event loop and
-     related functionality, in order to implement asynchronous networking,
-     timers, periodic events, and other scheduling tasks.
+   - \refdir{lib/evloop} -- Low-level event-loop.
 
-   - \refdir{lib/process} -- Utilities and compatibility code
-     to launch and manage subprocesses.
+   - \refdir{lib/process} -- Launch and manage subprocesses.
 
 ### What belongs in lib?
 
diff --git a/src/lib/math/lib_math.dox b/src/lib/math/lib_math.dox
index 0073731dc7..f20d7092b3 100644
--- a/src/lib/math/lib_math.dox
+++ b/src/lib/math/lib_math.dox
@@ -1,4 +1,8 @@
 /**
 @dir /lib/math
-@brief lib/math
+@brief lib/math: Floating-point math utilities.
+
+This module includes a bunch of floating-point compatibility code, and
+implementations for several probability distributions.
+
 **/
diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox
index eaca286044..9a7c8c4b2f 100644
--- a/src/lib/memarea/lib_memarea.dox
+++ b/src/lib/memarea/lib_memarea.dox
@@ -1,6 +1,6 @@
 /**
 @dir /lib/memarea
-@brief lib/memarea A fast arena-style allocator.
+@brief lib/memarea: A fast arena-style allocator.
 
 This module has a fast "arena" style allocator, where memory is freed all at
 once.  This kind of allocation is very fast and avoids fragmentation, at the
diff --git a/src/lib/meminfo/lib_meminfo.dox b/src/lib/meminfo/lib_meminfo.dox
index 433d6859ee..b57e60525e 100644
--- a/src/lib/meminfo/lib_meminfo.dox
+++ b/src/lib/meminfo/lib_meminfo.dox
@@ -1,4 +1,7 @@
 /**
 @dir /lib/meminfo
-@brief lib/meminfo
+@brief lib/meminfo: Inspecting malloc() usage.
+
+Only available when malloc() provides mallinfo() or something similar.
+
 **/
diff --git a/src/lib/net/lib_net.dox b/src/lib/net/lib_net.dox
index ca3c56a949..b4c00405d7 100644
--- a/src/lib/net/lib_net.dox
+++ b/src/lib/net/lib_net.dox
@@ -1,4 +1,8 @@
 /**
 @dir /lib/net
-@brief lib/net
+@brief lib/net: Low-level network-related code.
+
+This module includes address manipulation, compatibility wrappers,
+convenience functions, and so on.
+
 **/
diff --git a/src/lib/process/lib_process.dox b/src/lib/process/lib_process.dox
index 9059d66664..723c9f193d 100644
--- a/src/lib/process/lib_process.dox
+++ b/src/lib/process/lib_process.dox
@@ -1,4 +1,4 @@
 /**
 @dir /lib/process
-@brief lib/process
+@brief lib/process: Launch and manage subprocesses.
 **/
diff --git a/src/lib/pubsub/lib_pubsub.dox b/src/lib/pubsub/lib_pubsub.dox
index 3fd026cc09..c033660121 100644
--- a/src/lib/pubsub/lib_pubsub.dox
+++ b/src/lib/pubsub/lib_pubsub.dox
@@ -1,4 +1,16 @@
 /**
 @dir /lib/pubsub
-@brief lib/pubsub
+@brief lib/pubsub: Publish-subscribe message passing.
+
+This module wraps the \refdir{lib/dispatch} module, to provide a more
+ergonomic and type-safe approach to message passing.
+
+In general, we favor this mechanism for cases where higher-level modules
+need to be notified when something happens in lower-level modules. (The
+alternative would be calling up from the lower-level modules, which
+would be error-prone; or maintaining lists of function-pointers, which
+would be clumsy and tend to complicate the call graph.)
+
+See pubsub.c for more information.
+
 **/
diff --git a/src/lib/sandbox/lib_sandbox.dox b/src/lib/sandbox/lib_sandbox.dox
index 91d056d467..48eddac685 100644
--- a/src/lib/sandbox/lib_sandbox.dox
+++ b/src/lib/sandbox/lib_sandbox.dox
@@ -1,6 +1,6 @@
 /**
 @dir /lib/sandbox
-@brief lib/sandbox Linux seccomp2-based sandbox.
+@brief lib/sandbox: Linux seccomp2-based sandbox.
 
 This module uses Linux's seccomp2 facility via the
 [`libseccomp` library](https://github.com/seccomp/libseccomp), to restrict
diff --git a/src/lib/term/lib_term.dox b/src/lib/term/lib_term.dox
index d6010cb694..3bf2f960ab 100644
--- a/src/lib/term/lib_term.dox
+++ b/src/lib/term/lib_term.dox
@@ -1,4 +1,4 @@
 /**
 @dir /lib/term
-@brief lib/term
+@brief lib/term: Terminal operations (password input).
 **/
diff --git a/src/lib/thread/lib_thread.dox b/src/lib/thread/lib_thread.dox
index b1e24d824c..2773aa009d 100644
--- a/src/lib/thread/lib_thread.dox
+++ b/src/lib/thread/lib_thread.dox
@@ -1,4 +1,9 @@
 /**
 @dir /lib/thread
-@brief lib/thread
+@brief lib/thread: Mid-level threading.
+
+This module contains compatibility and convenience code for multithreading,
+except for low-level locks (which are in \refdir{lib/lock} and
+workqueue/threadpool code (which belongs in \refdir{lib/evloop}.)
+
 **/
diff --git a/src/lib/time/lib_time.dox b/src/lib/time/lib_time.dox
index 8e1e30859d..b76a31fb97 100644
--- a/src/lib/time/lib_time.dox
+++ b/src/lib/time/lib_time.dox
@@ -1,4 +1,11 @@
 /**
 @dir /lib/time
-@brief lib/time
+@brief lib/time: Higher-level time functions
+
+This includes both fine-grained timers and monotonic timers, along with
+wrappers for them to try to improve efficiency.
+
+For "what time is it" in UTC, see \refdir{lib/wallclock}.  For parsing and
+encoding times and dates, see \refdir{lib/encoding}.
+
 **/
diff --git a/src/lib/tls/lib_tls.dox b/src/lib/tls/lib_tls.dox
index 9558687f66..f0dba269e8 100644
--- a/src/lib/tls/lib_tls.dox
+++ b/src/lib/tls/lib_tls.dox
@@ -1,4 +1,13 @@
 /**
 @dir /lib/tls
-@brief lib/tls
+@brief lib/tls: TLS library wrappers
+
+This module has compatibility wrappers around the library (NSS or OpenSSL,
+depending on configuration) that Tor uses to implement the TLS link security
+protocol.
+
+It also implements the logic for some legacy TLS protocol usage we used to
+support in old versions of Tor, involving conditional delivery of certificate
+chains (v1 link protocol) and conditional renegotiation (v2 link protocol).
+
 **/
diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox
index 69dff85b5f..7d43fa6129 100644
--- a/src/lib/wallclock/lib_wallclock.dox
+++ b/src/lib/wallclock/lib_wallclock.dox
@@ -7,6 +7,7 @@ world agree it is?"  Generally, if you want something derived from UTC, this
 is the module for you.
 
 For versions of the time that are more local, more monotonic, or more
-accurate, see \refdir{lib/time}
+accurate, see \refdir{lib/time}.  For parsing and encoding times and dates,
+see \refdir{lib/encoding}.
 
 **/