commit 76e8effc7b8e747cd34188a5a27e6d792a66ba7e
parent fd271363296b89cb3a11e97e507546b3600fde59
Author: Nick Mathewson <nickm@torproject.org>
Date: Mon, 4 Nov 2019 11:51:38 -0500
Doxygen: document the rest of the directories in lib.
(This copies documentation from doc/HACKING/design, and edits for
concisensess and clarity.)
Diffstat:
22 files changed, 120 insertions(+), 52 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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}.
**/
