commit 9b13191192eefd79a1bfa5fbbd2e45c06ff1e005 Author: Nick Mathewson <nickm@torproject.org> Date: Mon Nov 4 11:12:27 2019 -0500 Doxygen: use \refdir everywhere. This commit was generated with: find src -name '*.dox' |xargs perl -i -pe 's{\\ref src/(\S+) \"\S+}{\\refdir{$1}};' --- Doxyfile.in | 1 + src/lib/dispatch/lib_dispatch.dox | 2 +- src/lib/lib.dox | 82 +++++++++++++-------------- src/lib/log/lib_log.dox | 2 +- src/lib/smartlist_core/lib_smartlist_core.dox | 2 +- src/lib/wallclock/lib_wallclock.dox | 2 +- 6 files changed, 46 insertions(+), 45 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index bb0d75cc9..547a7db19 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -255,6 +255,7 @@ TAB_SIZE = 8 # a double escape (\\{ and \\}) ALIASES = + ALIASES += refdir{1}="\ref @top_srcdir@/src/\1 \"\1\"" # This tag can be used to specify a number of word-keyword mappings (TCL only). diff --git a/src/lib/dispatch/lib_dispatch.dox b/src/lib/dispatch/lib_dispatch.dox index 24a4b79e3..955b7df64 100644 --- a/src/lib/dispatch/lib_dispatch.dox +++ b/src/lib/dispatch/lib_dispatch.dox @@ -6,7 +6,7 @@ This module provides a general in-process "message dispatch" system in which typed messages are sent on channels. The dispatch.h header has far more information. -It is used by by \ref src/lib/pubsub "lib/pubsub" to implement our general +It is used by by \refdir{lib/pubsub} to implement our general inter-module publish/subscribe system. This is not a fancy multi-threaded many-to-many dispatcher as you may be used diff --git a/src/lib/lib.dox b/src/lib/lib.dox index 1d3bc3a3f..b4babf798 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -14,125 +14,125 @@ modules, sorted from lowest to highest level, by running As of this writing, the library modules are (from lowest to highest level): - - \ref src/lib/cc "lib/cc" -- Macros for managing the C compiler and + - \refdir{lib/cc} -- Macros for managing the C compiler and language. - - \ref src/lib/version "lib/version" -- Holds the current version of Tor. + - \refdir{lib/version} -- Holds the current version of Tor. - - \ref src/lib/testsupport "lib/testsupport" -- Helpers for making + - \refdir{lib/testsupport} -- Helpers for making test-only code, and test mocking support. - - \ref src/lib/defs "lib/defs" -- Lowest-level constants. + - \refdir{lib/defs} -- Lowest-level constants. - - \ref src/lib/subsys "lib/subsys" -- Types used for declaring a + - \refdir{lib/subsys} -- Types used for declaring a "subsystem". (_A subsystem is a module with support for initialization, shutdown, configuration, and so on._) - - \ref src/lib/conf "lib/conf" -- For declaring configuration options. + - \refdir{lib/conf} -- For declaring configuration options. - - \ref src/lib/arch "lib/arch" -- For handling differences in CPU + - \refdir{lib/arch} -- For handling differences in CPU architecture. - - \ref src/lib/err "lib/err" -- Lowest-level error handling code. + - \refdir{lib/err} -- Lowest-level error handling code. - - \ref src/lib/malloc "lib/malloc" -- Memory management. + - \refdir{lib/malloc} -- Memory management. management. - - \ref src/lib/intmath "lib/intmath" -- Integer mathematics. + - \refdir{lib/intmath} -- Integer mathematics. - - \ref src/lib/fdio "lib/fdio" -- For + - \refdir{lib/fdio} -- For reading and writing n file descriptors. - - \ref src/lib/lock "lib/lock" -- Simple locking support. + - \refdir{lib/lock} -- Simple locking support. (_Lower-level than the rest of the threading code._) - - \ref src/lib/ctime "lib/ctime" -- Constant-time code to avoid + - \refdir{lib/ctime} -- Constant-time code to avoid side-channels. - - \ref src/lib/string "lib/string" -- Low-level string manipulation. + - \refdir{lib/string} -- Low-level string manipulation. - - \ref src/lib/wallclock "lib/wallclock" -- + - \refdir{lib/wallclock} -- For inspecting and manipulating the current (UTC) time. - - \ref src/lib/osinfo "lib/osinfo" -- For inspecting the OS version + - \refdir{lib/osinfo} -- For inspecting the OS version and capabilities. - - \ref src/lib/smartlist_core "lib/smartlist_core" -- The bare-bones + - \refdir{lib/smartlist_core} -- The bare-bones pieces of our dynamic array ("smartlist") implementation. - - \ref src/lib/log "lib/log" -- Log messages to files, syslogs, etc. + - \refdir{lib/log} -- Log messages to files, syslogs, etc. - - \ref src/lib/container "lib/container" -- General purpose containers, + - \refdir{lib/container} -- General purpose containers, including dynamic arrays ("smartlists"), hashtables, bit arrays, etc. - - \ref src/lib/trace "lib/trace" -- A general-purpose API + - \refdir{lib/trace} -- A general-purpose API function-tracing functionality Tor. (_Currently not much used._) - - \ref src/lib/thread "lib/thread" -- Threading compatibility and utility + - \refdir{lib/thread} -- Threading compatibility and utility functionality, other than low-level locks (which are in \ref src/lib/lock "lib/lock") and workqueue/threadpool code (which belongs - in \ref src/lib/evloop "lib/evloop"). + in \refdir{lib/evloop} - - \ref src/lib/term "lib/term" -- Terminal manipulation + - \refdir{lib/term} -- Terminal manipulation (like reading a password from the user). - - \ref src/lib/memarea "lib/memarea" -- A fast + - \refdir{lib/memarea} -- A fast "arena" style allocator, where the data is freed all at once. - - \ref src/lib/encoding "lib/encoding" -- Encoding + - \refdir{lib/encoding} -- Encoding data in various formats, datatypes, and transformations. - - \ref src/lib/dispatch "lib/dispatch" -- A general-purpose in-process + - \refdir{lib/dispatch} -- A general-purpose in-process message delivery system. - - \ref src/lib/sandbox "lib/sandbox" -- Our Linux seccomp2 sandbox + - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox implementation. - - \ref src/lib/pubsub "lib/pubsub" -- Code and macros to implement our + - \refdir{lib/pubsub} -- Code and macros to implement our publish/subscribe message passing system. - - \ref src/lib/fs "lib/fs" -- Utility and compatibility code for + - \refdir{lib/fs} -- Utility and compatibility code for manipulating files, filenames, directories, and so on. - - \ref src/lib/confmgt "lib/confmgt" -- Code to parse, encode, and + - \refdir{lib/confmgt} -- Code to parse, encode, and manipulate our configuration files, state files, and so forth. - - \ref src/lib/crypt_ops "lib/crypt_ops" -- Cryptographic operations. This + - \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. - - \ref src/lib/meminfo "lib/meminfo" -- Functions for inspecting our + - \refdir{lib/meminfo} -- Functions for inspecting our memory usage, if the malloc implementation exposes that to us. - - \ref src/lib/time "lib/time" -- Higher level time functions, including + - \refdir{lib/time} -- Higher level time functions, including fine-gained and monotonic timers. - - \ref src/lib/math "lib/math" -- Floating-point mathematical utilities, + - \refdir{lib/math} -- Floating-point mathematical utilities, including compatibility code, and probability distributions. - - \ref src/lib/buf "lib/buf" -- A general purpose queued buffer + - \refdir{lib/buf} -- A general purpose queued buffer implementation, similar to the BSD kernel's "mbuf" structure. - - \ref src/lib/net "lib/net" -- Networking code, including address + - \refdir{lib/net} -- Networking code, including address manipulation, compatibility wrappers, - - \ref src/lib/compress "lib/compress" -- A compatibility wrapper around + - \refdir{lib/compress} -- A compatibility wrapper around several compression libraries, currently including zlib, zstd, and lzma. - - \ref src/lib/geoip "lib/geoip" -- Utilities to manage geoip (IP to + - \refdir{lib/geoip} -- Utilities to manage geoip (IP to country) lookups and formats. - - \ref src/lib/tls "lib/tls" -- Compatibility wrappers around the library + - \refdir{lib/tls} -- Compatibility wrappers around the library (NSS or OpenSSL, depending on configuration) that Tor uses to implement the TLS link security protocol. - - \ref src/lib/evloop "lib/evloop" -- Tools to manage the event loop and + - \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. - - \ref src/lib/process "lib/process" -- Utilities and compatibility code + - \refdir{lib/process} -- Utilities and compatibility code to launch and manage subprocesses. ### What belongs in lib? diff --git a/src/lib/log/lib_log.dox b/src/lib/log/lib_log.dox index b6d242917..a772dc320 100644 --- a/src/lib/log/lib_log.dox +++ b/src/lib/log/lib_log.dox @@ -3,7 +3,7 @@ @brief lib/log: Log messages to files, syslogs, etc. You can think of this as the logical "midpoint" of the -\ref src/lib "library code": much of the higher-level code is higher-level +\refdir{lib} code": much of the higher-level code is higher-level _because_ it uses the logging module, and much of the lower-level code is specifically written to avoid having to log, because the logging module depends on it. diff --git a/src/lib/smartlist_core/lib_smartlist_core.dox b/src/lib/smartlist_core/lib_smartlist_core.dox index 5e3ffd1f0..73c3b6905 100644 --- a/src/lib/smartlist_core/lib_smartlist_core.dox +++ b/src/lib/smartlist_core/lib_smartlist_core.dox @@ -5,7 +5,7 @@ A `smartlist_t` is a dynamic array type for holding `void *`. We use it throughout the rest of the codebase. -There are higher-level pieces in \ref src/lib/container "lib/container", but +There are higher-level pieces in \refdir{lib/container} but the ones in lib/smartlist_core are used by the logging code, and therefore cannot use the logging code. diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index 03966aecc..69dff85b5 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -7,6 +7,6 @@ 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 \ref src/lib/time "lib/time". +accurate, see \refdir{lib/time} **/