[tor/master] File-level documentation for some of src/lib.
commit cb1a3674ebb3826d9e1e56146210bd79cb4a42f0 Author: Nick Mathewson <nickm@torproject.org> Date: Sun Jul 1 20:22:55 2018 -0400 File-level documentation for some of src/lib. --- src/lib/arch/bytes.h | 7 +++++++ src/lib/cc/torint.h | 7 ++++++- src/lib/compress/compress.c | 5 ++++- src/lib/compress/compress_buf.c | 6 ++++++ src/lib/container/bitarray.h | 6 ++++++ src/lib/container/bloomfilt.h | 6 ++++++ src/lib/container/buffers.c | 4 ++++ src/lib/container/buffers.h | 3 +-- src/lib/container/map.c | 5 +++-- src/lib/container/map.h | 6 ++++++ src/lib/container/order.h | 6 ++++++ src/lib/container/smartlist.c | 12 +++++++++--- src/lib/container/smartlist.h | 6 ++++++ src/lib/crypt_ops/crypto_pwbox.h | 7 ++++++- src/lib/crypt_ops/crypto_s2k.h | 7 ++++++- src/lib/defs/digest_sizes.h | 9 +++++++++ src/lib/encoding/binascii.h | 6 ++++++ src/lib/encoding/confline.c | 11 +++++++++++ src/lib/encoding/confline.h | 6 ++++++ src/lib/encoding/cstring.c | 6 ++++++ src/lib/encoding/cstring.h | 6 ++++++ src/lib/encoding/keyval.c | 6 ++++++ src/lib/encoding/keyval.h | 6 ++++++ src/lib/encoding/time_fmt.c | 10 ++++++++++ src/lib/encoding/time_fmt.h | 6 ++++++ src/lib/err/backtrace.c | 4 ++++ src/lib/err/backtrace.h | 6 ++++++ src/lib/err/torerr.c | 8 ++++++++ src/lib/fdio/fdio.c | 6 ++++++ src/lib/fdio/fdio.h | 6 ++++++ src/lib/fs/conffile.c | 6 ++++++ src/lib/fs/conffile.h | 6 ++++++ src/lib/fs/dir.c | 7 +++++++ src/lib/fs/dir.h | 6 ++++++ src/lib/fs/files.c | 6 ++++++ src/lib/fs/files.h | 6 ++++++ src/lib/fs/freespace.c | 6 ++++++ src/lib/fs/lockfile.c | 7 +++++++ src/lib/fs/lockfile.h | 6 ++++++ src/lib/fs/mmap.c | 6 ++++++ src/lib/fs/mmap.h | 6 ++++++ src/lib/fs/path.c | 6 ++++++ src/lib/fs/path.h | 6 ++++++ src/lib/fs/storagedir.c | 11 +++++++++++ src/lib/fs/storagedir.h | 6 ++++++ src/lib/fs/userdb.c | 6 ++++++ src/lib/fs/userdb.h | 6 ++++++ src/lib/fs/winlib.c | 9 +++++++++ src/lib/fs/winlib.h | 6 ++++++ src/lib/intmath/addsub.c | 8 ++++++++ src/lib/intmath/addsub.h | 6 ++++++ src/lib/intmath/bits.c | 6 ++++++ src/lib/intmath/bits.h | 6 ++++++ src/lib/intmath/cmp.h | 6 ++++++ src/lib/intmath/logic.h | 6 ++++++ src/lib/intmath/muldiv.c | 6 ++++++ src/lib/intmath/muldiv.h | 6 ++++++ src/lib/intmath/weakrng.c | 9 +++++++++ src/lib/intmath/weakrng.h | 6 ++++++ src/lib/lock/compat_mutex.c | 6 ++++++ src/lib/lock/compat_mutex.h | 6 ++++++ src/lib/lock/compat_mutex_pthreads.c | 6 ++++++ src/lib/lock/compat_mutex_winthreads.c | 6 ++++++ src/lib/math/fp.c | 6 ++++++ src/lib/math/fp.h | 6 ++++++ src/lib/math/laplace.c | 6 ++++++ src/lib/math/laplace.h | 6 ++++++ src/lib/memarea/memarea.c | 4 +++- src/lib/memarea/memarea.h | 7 ++++++- src/lib/meminfo/meminfo.c | 7 +++++++ src/lib/meminfo/meminfo.h | 6 ++++++ src/lib/net/alertsock.c | 11 +++++++++++ src/lib/net/alertsock.h | 6 ++++++ src/lib/net/buffers_net.h | 5 +++-- 74 files changed, 463 insertions(+), 15 deletions(-) diff --git a/src/lib/arch/bytes.h b/src/lib/arch/bytes.h index 4359b0f72..a2e2224d3 100644 --- a/src/lib/arch/bytes.h +++ b/src/lib/arch/bytes.h @@ -6,6 +6,13 @@ #ifndef TOR_BYTES_H #define TOR_BYTES_H +/** + * \file bytes.h + * + * \brief Inline functions for reading and writing multibyte values from + * the middle of strings, and for manipulating byte order. + **/ + #include <string.h> #include "lib/cc/torint.h" diff --git a/src/lib/cc/torint.h b/src/lib/cc/torint.h index 55b15402f..5d536e78b 100644 --- a/src/lib/cc/torint.h +++ b/src/lib/cc/torint.h @@ -11,6 +11,12 @@ #ifndef TOR_TORINT_H #define TOR_TORINT_H +/** + * \file torint.h + * + * \brief Integer definitions used throughout Tor. + **/ + #include "orconfig.h" #ifdef HAVE_STDINT_H @@ -376,4 +382,3 @@ typedef uint32_t uintptr_t; #define SIZE_T_CEILING ((size_t)(SSIZE_MAX-16)) #endif /* !defined(TOR_TORINT_H) */ - diff --git a/src/lib/compress/compress.c b/src/lib/compress/compress.c index 2cb5dbaec..e87e788f1 100644 --- a/src/lib/compress/compress.c +++ b/src/lib/compress/compress.c @@ -5,7 +5,10 @@ /** * \file compress.c - * \brief Common compression API. + * \brief Common compression API implementation. + * + * This file provides a unified interface to all the compression libraries Tor + * knows how to use. **/ #include "orconfig.h" diff --git a/src/lib/compress/compress_buf.c b/src/lib/compress/compress_buf.c index 4b8877238..63ee9e010 100644 --- a/src/lib/compress/compress_buf.c +++ b/src/lib/compress/compress_buf.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compress_buf.c + * + * \brief Working with compressed data in buffers. + **/ + #define BUFFERS_PRIVATE #include "lib/cc/compat_compiler.h" #include "lib/container/buffers.h" diff --git a/src/lib/container/bitarray.h b/src/lib/container/bitarray.h index 2cea433fb..172d56cc0 100644 --- a/src/lib/container/bitarray.h +++ b/src/lib/container/bitarray.h @@ -6,6 +6,12 @@ #ifndef TOR_BITARRAY_H #define TOR_BITARRAY_H +/** + * \file bitarray.h + * + * \brief Implements a variable-sized (but non-resizeable) bit-array. + **/ + #include "orconfig.h" #include <string.h> #include "lib/cc/torint.h" diff --git a/src/lib/container/bloomfilt.h b/src/lib/container/bloomfilt.h index 577acf5e4..14f909cb1 100644 --- a/src/lib/container/bloomfilt.h +++ b/src/lib/container/bloomfilt.h @@ -6,6 +6,12 @@ #ifndef TOR_BLOOMFILT_H #define TOR_BLOOMFILT_H +/** + * \file bloomfilt.h + * + * \brief Header for bloomfilt.c + **/ + #include "orconfig.h" #include "lib/cc/torint.h" #include "lib/container/bitarray.h" diff --git a/src/lib/container/buffers.c b/src/lib/container/buffers.c index 0e98033bf..5849704e3 100644 --- a/src/lib/container/buffers.c +++ b/src/lib/container/buffers.c @@ -16,6 +16,10 @@ * buffers: one for incoming data, and one for outcoming data. These are fed * and drained from functions in connection.c, trigged by events that are * monitored in main.c. + * + * This module only handles the buffer implementation itself. To use a buffer + * with the network, a compressor, or a TLS connection, see the other buffer_* + * modules. **/ #define BUFFERS_PRIVATE diff --git a/src/lib/container/buffers.h b/src/lib/container/buffers.h index 8b16fb298..c48f83cfc 100644 --- a/src/lib/container/buffers.h +++ b/src/lib/container/buffers.h @@ -6,6 +6,7 @@ /** * \file buffers.h + * * \brief Header file for buffers.c. **/ @@ -20,8 +21,6 @@ typedef struct buf_t buf_t; -struct tor_compress_state_t; - buf_t *buf_new(void); buf_t *buf_new_with_capacity(size_t size); size_t buf_get_default_chunk_size(const buf_t *buf); diff --git a/src/lib/container/map.c b/src/lib/container/map.c index 3d84356cc..0602eac89 100644 --- a/src/lib/container/map.c +++ b/src/lib/container/map.c @@ -4,8 +4,9 @@ /* See LICENSE for licensing information */ /** - * \file container.c - * \brief Hash table implementations of a string-to-void* map, and of + * \file map.c + * + * \brief Hash-table implementations of a string-to-void* map, and of * a digest-to-void* map. **/ diff --git a/src/lib/container/map.h b/src/lib/container/map.h index ac21c2871..ff7162268 100644 --- a/src/lib/container/map.h +++ b/src/lib/container/map.h @@ -6,6 +6,12 @@ #ifndef TOR_MAP_H #define TOR_MAP_H +/** + * \file map.h + * + * \brief Headers for map.c. + **/ + #include "lib/testsupport/testsupport.h" #include "lib/cc/torint.h" diff --git a/src/lib/container/order.h b/src/lib/container/order.h index bd23750d5..f0675f347 100644 --- a/src/lib/container/order.h +++ b/src/lib/container/order.h @@ -6,6 +6,12 @@ #ifndef TOR_ORDER_H #define TOR_ORDER_H +/** + * \file order.h + * + * \brief Header for order.c. + **/ + #include "lib/cc/compat_compiler.h" #include "lib/cc/torint.h" diff --git a/src/lib/container/smartlist.c b/src/lib/container/smartlist.c index 9025cab9f..63c50e045 100644 --- a/src/lib/container/smartlist.c +++ b/src/lib/container/smartlist.c @@ -4,9 +4,15 @@ /* See LICENSE for licensing information */ /** - * \file container.c - * \brief Implements a smartlist (a resizable array) along - * with helper functions to use smartlists. + * \file smartlist.c + * + * \brief Higher-level functions for the "smartlist" resizeable array + * abstraction. + * + * The functions declared here use higher-level functionality than those in + * smartlist_core.c, and handle things like smartlists of different types, + * sorting, searching, heap-structured smartlists, and other convenience + * functions. **/ #include "lib/container/smartlist.h" diff --git a/src/lib/container/smartlist.h b/src/lib/container/smartlist.h index 76ecbda0a..3b19cbfce 100644 --- a/src/lib/container/smartlist.h +++ b/src/lib/container/smartlist.h @@ -6,6 +6,12 @@ #ifndef TOR_SMARTLIST_H #define TOR_SMARTLIST_H +/** + * \file smartlist.h + * + * \brief Header for smartlist.c + **/ + #include <stdarg.h> #include "lib/smartlist_core/smartlist_core.h" diff --git a/src/lib/crypt_ops/crypto_pwbox.h b/src/lib/crypt_ops/crypto_pwbox.h index 9ed35a150..00fabd091 100644 --- a/src/lib/crypt_ops/crypto_pwbox.h +++ b/src/lib/crypt_ops/crypto_pwbox.h @@ -1,6 +1,12 @@ /* Copyright (c) 2014-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file crypto_pwbox.h + * + * \brief Header for crypto_pwbox.c + **/ + #ifndef CRYPTO_PWBOX_H_INCLUDED_ #define CRYPTO_PWBOX_H_INCLUDED_ @@ -20,4 +26,3 @@ int crypto_unpwbox(uint8_t **out, size_t *outlen_out, const char *secret, size_t secret_len); #endif /* !defined(CRYPTO_PWBOX_H_INCLUDED_) */ - diff --git a/src/lib/crypt_ops/crypto_s2k.h b/src/lib/crypt_ops/crypto_s2k.h index b270897b6..2429185b5 100644 --- a/src/lib/crypt_ops/crypto_s2k.h +++ b/src/lib/crypt_ops/crypto_s2k.h @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file crypto_s2k.h + * + * \brief Header for crypto_s2k.c + **/ + #ifndef TOR_CRYPTO_S2K_H_INCLUDED #define TOR_CRYPTO_S2K_H_INCLUDED @@ -70,4 +76,3 @@ STATIC int secret_to_key_compute_key(uint8_t *key_out, size_t key_out_len, #endif /* defined(CRYPTO_S2K_PRIVATE) */ #endif /* !defined(TOR_CRYPTO_S2K_H_INCLUDED) */ - diff --git a/src/lib/defs/digest_sizes.h b/src/lib/defs/digest_sizes.h index f426fff20..dd772cae0 100644 --- a/src/lib/defs/digest_sizes.h +++ b/src/lib/defs/digest_sizes.h @@ -7,6 +7,15 @@ #ifndef TOR_DIGEST_SIZES_H #define TOR_DIGEST_SIZES_H +/** + * \file digest_sizes.h + * + * \brief Definitions for common sizes of cryptographic digests. + * + * Tor uses digests throughout its codebase, even in parts that don't actually + * calculate the digests. + **/ + /** Length of the output of our message digest. */ #define DIGEST_LEN 20 /** Length of the output of our second (improved) message digests. (For now diff --git a/src/lib/encoding/binascii.h b/src/lib/encoding/binascii.h index 67f9eb0e8..23cbaa707 100644 --- a/src/lib/encoding/binascii.h +++ b/src/lib/encoding/binascii.h @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file binascii.h + * + * \brief Header for binascii.c + **/ + #ifndef TOR_BINASCII_H #define TOR_BINASCII_H diff --git a/src/lib/encoding/confline.c b/src/lib/encoding/confline.c index 7f535b321..3486b6a82 100644 --- a/src/lib/encoding/confline.c +++ b/src/lib/encoding/confline.c @@ -4,6 +4,17 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file confline.c + * + * \brief Functions to manipulate a linked list of key-value pairs, of the + * type used in Tor's configuration files. + * + * Tor uses the config_line_t type and its associated serialized format for + * human-readable key-value pairs in many places, including its configuration, + * its state files, its consensus cache, and so on. + **/ + #include "lib/encoding/confline.h" #include "lib/encoding/cstring.h" #include "lib/log/torlog.h" diff --git a/src/lib/encoding/confline.h b/src/lib/encoding/confline.h index f03faed5e..41f120094 100644 --- a/src/lib/encoding/confline.h +++ b/src/lib/encoding/confline.h @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file confline.h + * + * \brief Header for confline.c + **/ + #ifndef TOR_CONFLINE_H #define TOR_CONFLINE_H diff --git a/src/lib/encoding/cstring.c b/src/lib/encoding/cstring.c index 86c17f0d2..994a52e70 100644 --- a/src/lib/encoding/cstring.c +++ b/src/lib/encoding/cstring.c @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file cstring.c + * + * \brief Decode data that has been written as a C literal. + **/ + #include "lib/encoding/cstring.h" #include "lib/log/torlog.h" #include "lib/log/util_bug.h" diff --git a/src/lib/encoding/cstring.h b/src/lib/encoding/cstring.h index 3dff5e7f7..2da109d95 100644 --- a/src/lib/encoding/cstring.h +++ b/src/lib/encoding/cstring.h @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file cstring.h + * + * \brief Header for cstring.c + **/ + #ifndef TOR_CSTRING_H #define TOR_CSTRING_H diff --git a/src/lib/encoding/keyval.c b/src/lib/encoding/keyval.c index cffd6f6db..53ee776fe 100644 --- a/src/lib/encoding/keyval.c +++ b/src/lib/encoding/keyval.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file keyval.c + * + * \brief Handle data encoded as a key=value pair. + **/ + #include "orconfig.h" #include "lib/encoding/keyval.h" #include "lib/log/escape.h" diff --git a/src/lib/encoding/keyval.h b/src/lib/encoding/keyval.h index 745855520..8bf079762 100644 --- a/src/lib/encoding/keyval.h +++ b/src/lib/encoding/keyval.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file keyval.h + * + * \brief Header for keyval.c + **/ + #ifndef TOR_KEYVAL_H #define TOR_KEYVAL_H diff --git a/src/lib/encoding/time_fmt.c b/src/lib/encoding/time_fmt.c index ef60f17e3..ea9c8e9fd 100644 --- a/src/lib/encoding/time_fmt.c +++ b/src/lib/encoding/time_fmt.c @@ -4,6 +4,16 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file time_fmt.c + * + * \brief Encode and decode time in various formats. + * + * This module is higher-level than the conversion functions in "wallclock", + * and handles a larger variety of types. It converts between different time + * formats, and encodes and decodes them from strings. + **/ + #include "lib/encoding/time_fmt.h" #include "lib/log/torlog.h" #include "lib/log/escape.h" diff --git a/src/lib/encoding/time_fmt.h b/src/lib/encoding/time_fmt.h index 41508ce5e..2892442ad 100644 --- a/src/lib/encoding/time_fmt.h +++ b/src/lib/encoding/time_fmt.h @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file time_fmt.h + * + * \brief Header for time_fmt.c + **/ + #ifndef TOR_TIME_FMT_H #define TOR_TIME_FMT_H diff --git a/src/lib/err/backtrace.c b/src/lib/err/backtrace.c index cded6459f..5f5ecd3c3 100644 --- a/src/lib/err/backtrace.c +++ b/src/lib/err/backtrace.c @@ -11,6 +11,10 @@ * family of functions, which are sometimes provided by libc and sometimes * provided by libexecinfo. We tie into the sigaction() backend in order to * detect crashes. + * + * This is one of the lowest-level modules, since nearly everything needs to + * be able to log an error. As such, it doesn't call the log module or any + * other higher-level modules directly. */ #include "orconfig.h" diff --git a/src/lib/err/backtrace.h b/src/lib/err/backtrace.h index 7f7742843..70c43484f 100644 --- a/src/lib/err/backtrace.h +++ b/src/lib/err/backtrace.h @@ -4,6 +4,12 @@ #ifndef TOR_BACKTRACE_H #define TOR_BACKTRACE_H +/** + * \file backtrace.h + * + * \brief Header for backtrace.c + **/ + #include "orconfig.h" #include "lib/cc/compat_compiler.h" diff --git a/src/lib/err/torerr.c b/src/lib/err/torerr.c index 8d8f694f1..f9e139f96 100644 --- a/src/lib/err/torerr.c +++ b/src/lib/err/torerr.c @@ -9,6 +9,14 @@ * * \brief Handling code for unrecoverable emergencies, at a lower level * than the logging code. + * + * There are plenty of places that things can go wrong in Tor's backend + * libraries: the allocator can fail, the locking subsystem can fail, and so + * on. But since these subsystems are used themselves by the logging module, + * they can't use the logging code directly to report their errors. + * + * As a workaround, the logging code provides this module with a set of raw + * fds to be used for reporting errors in the lowest-level Tor code. */ #include "orconfig.h" diff --git a/src/lib/fdio/fdio.c b/src/lib/fdio/fdio.c index 21577e184..afb57e03d 100644 --- a/src/lib/fdio/fdio.c +++ b/src/lib/fdio/fdio.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file fdio.c + * + * \brief Low-level compatibility wrappers for fd-based IO. + **/ + #include "orconfig.h" #ifdef HAVE_UNISTD_H diff --git a/src/lib/fdio/fdio.h b/src/lib/fdio/fdio.h index 0fb3ed1e6..c8f05455b 100644 --- a/src/lib/fdio/fdio.h +++ b/src/lib/fdio/fdio.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file fdio.h + * + * \brief Header for fdio.c + **/ + #ifndef TOR_FDIO_H #define TOR_FDIO_H diff --git a/src/lib/fs/conffile.c b/src/lib/fs/conffile.c index 37bd9f036..600c7f6b7 100644 --- a/src/lib/fs/conffile.c +++ b/src/lib/fs/conffile.c @@ -4,6 +4,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file conffile.h + * + * \brief Read configuration files from disk, with full `%include` support. + **/ + #include "lib/fs/conffile.h" #include "lib/container/smartlist.h" diff --git a/src/lib/fs/conffile.h b/src/lib/fs/conffile.h index bd8250b00..a926f4ac0 100644 --- a/src/lib/fs/conffile.h +++ b/src/lib/fs/conffile.h @@ -7,6 +7,12 @@ #ifndef TOR_CONFFILE_H #define TOR_CONFFILE_H +/** + * \file conffile.h + * + * \brief Header for conffile.c + **/ + struct smartlist_t; struct config_line_t; diff --git a/src/lib/fs/dir.c b/src/lib/fs/dir.c index 9f09327d8..cc339f747 100644 --- a/src/lib/fs/dir.c +++ b/src/lib/fs/dir.c @@ -3,6 +3,13 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file dir.c + * + * \brief Read directories, and create directories with restrictive + * permissions. + **/ + #include "lib/fs/dir.h" #include "lib/fs/path.h" #include "lib/fs/userdb.h" diff --git a/src/lib/fs/dir.h b/src/lib/fs/dir.h index 925211fbd..61a04e6d5 100644 --- a/src/lib/fs/dir.h +++ b/src/lib/fs/dir.h @@ -6,6 +6,12 @@ #ifndef TOR_DIR_H #define TOR_DIR_H +/** + * \file dir.h + * + * \brief Header for dir.c + **/ + #include "lib/cc/compat_compiler.h" #include "lib/testsupport/testsupport.h" diff --git a/src/lib/fs/files.c b/src/lib/fs/files.c index 0335f6dc5..4e0a398ba 100644 --- a/src/lib/fs/files.c +++ b/src/lib/fs/files.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file files.h + * + * \brief Wrappers for reading and writing data to files on disk. + **/ + #ifdef _WIN32 #include <windows.h> #endif diff --git a/src/lib/fs/files.h b/src/lib/fs/files.h index be4ec485f..5a12eb821 100644 --- a/src/lib/fs/files.h +++ b/src/lib/fs/files.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file files.h + * + * \brief Header for files.c + **/ + #ifndef TOR_FS_H #define TOR_FS_H diff --git a/src/lib/fs/freespace.c b/src/lib/fs/freespace.c index 926b17dbd..2dbba3c5f 100644 --- a/src/lib/fs/freespace.c +++ b/src/lib/fs/freespace.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file freespace.c + * + * \brief Find the available disk space on the current volume. + **/ + #include "lib/fs/files.h" #include "lib/cc/torint.h" diff --git a/src/lib/fs/lockfile.c b/src/lib/fs/lockfile.c index 3fc9cd426..972fd5658 100644 --- a/src/lib/fs/lockfile.c +++ b/src/lib/fs/lockfile.c @@ -3,6 +3,13 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file lockfile.c + * + * \brief Implements lock files to prevent two Tor processes from using the + * same data directory at the same time. + **/ + #include "orconfig.h" #include "lib/fs/files.h" #include "lib/fs/lockfile.h" diff --git a/src/lib/fs/lockfile.h b/src/lib/fs/lockfile.h index 1c5bb023b..e26349811 100644 --- a/src/lib/fs/lockfile.h +++ b/src/lib/fs/lockfile.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file lockfile.h + * + * \brief Header for lockfile.c + **/ + #ifndef TOR_LOCKFILE_H #define TOR_LOCKFILE_H diff --git a/src/lib/fs/mmap.c b/src/lib/fs/mmap.c index 6d69fd5e7..2d758c1b5 100644 --- a/src/lib/fs/mmap.c +++ b/src/lib/fs/mmap.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file mmap.c + * + * \brief Cross-platform support for mapping files into our address space. + **/ + #include "lib/fs/mmap.h" #include "lib/fs/files.h" #include "lib/log/torlog.h" diff --git a/src/lib/fs/mmap.h b/src/lib/fs/mmap.h index b0585775f..125f36880 100644 --- a/src/lib/fs/mmap.h +++ b/src/lib/fs/mmap.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file mmap.h + * + * \brief Header for mmap.c + **/ + #ifndef TOR_MMAP_H #define TOR_MMAP_H diff --git a/src/lib/fs/path.c b/src/lib/fs/path.c index 68cda6776..708ff0505 100644 --- a/src/lib/fs/path.c +++ b/src/lib/fs/path.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file path.c + * + * \brief Manipulate strings that contain filesystem paths. + **/ + #include "lib/fs/path.h" #include "lib/malloc/util_malloc.h" #include "lib/log/torlog.h" diff --git a/src/lib/fs/path.h b/src/lib/fs/path.h index a3073a99e..384d1f514 100644 --- a/src/lib/fs/path.h +++ b/src/lib/fs/path.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file path.h + * + * \brief Header for path.c + **/ + #ifndef TOR_PATH_H #define TOR_PATH_H diff --git a/src/lib/fs/storagedir.c b/src/lib/fs/storagedir.c index d013e4550..1cda2374d 100644 --- a/src/lib/fs/storagedir.c +++ b/src/lib/fs/storagedir.c @@ -1,6 +1,17 @@ /* Copyright (c) 2017-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file storagedir.c + * + * \brief An abstraction for a directory full of similar files. + * + * Storagedirs are used by our consensus cache code, and may someday also get + * used for unparseable objects. A large part of the need for this type is to + * work around the limitations in our sandbox code, where all filenames need + * to be registered in advance. + **/ + #include "lib/fs/storagedir.h" #include "lib/container/smartlist.h" diff --git a/src/lib/fs/storagedir.h b/src/lib/fs/storagedir.h index 1ecb1c0a1..58594b463 100644 --- a/src/lib/fs/storagedir.h +++ b/src/lib/fs/storagedir.h @@ -1,6 +1,12 @@ /* Copyright (c) 2017-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file storagedir.h + * + * \brief Header for storagedir.c + **/ + #ifndef TOR_STORAGEDIR_H #define TOR_STORAGEDIR_H diff --git a/src/lib/fs/userdb.c b/src/lib/fs/userdb.c index b7abbc781..3d7a9da59 100644 --- a/src/lib/fs/userdb.c +++ b/src/lib/fs/userdb.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file userdb.c + * + * \brief Access the POSIX user database. + **/ + #include "lib/fs/userdb.h" #ifndef _WIN32 diff --git a/src/lib/fs/userdb.h b/src/lib/fs/userdb.h index 31c891ede..3b3ab6ed2 100644 --- a/src/lib/fs/userdb.h +++ b/src/lib/fs/userdb.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file userdb.h + * + * \brief Header for userdb.c + **/ + #ifndef TOR_USERDB_H #define TOR_USERDB_H diff --git a/src/lib/fs/winlib.c b/src/lib/fs/winlib.c index 7a88a841a..532807c03 100644 --- a/src/lib/fs/winlib.c +++ b/src/lib/fs/winlib.c @@ -3,6 +3,15 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file winlib.c + * + * \brief Find and load windows system libraries. + * + * We use this function to dynamically load code at runtime that might not be + * available on all versions of Windows that we support. + **/ + #ifdef _WIN32 #include "lib/fs/winlib.h" diff --git a/src/lib/fs/winlib.h b/src/lib/fs/winlib.h index f53f04645..5b10b9b78 100644 --- a/src/lib/fs/winlib.h +++ b/src/lib/fs/winlib.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file winlib.h + * + * \brief Header for winlib.c + **/ + #ifndef TOR_WINLIB_H #define TOR_WINLIB_H diff --git a/src/lib/intmath/addsub.c b/src/lib/intmath/addsub.c index 816c5a2bd..fcfdca682 100644 --- a/src/lib/intmath/addsub.c +++ b/src/lib/intmath/addsub.c @@ -3,6 +3,14 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file addsub.c + * + * \brief Helpers for addition and subtraction. + * + * Currently limited to non-wrapping (saturating) addition. + **/ + #include "lib/intmath/addsub.h" #include "lib/cc/compat_compiler.h" diff --git a/src/lib/intmath/addsub.h b/src/lib/intmath/addsub.h index 5277adfa4..5bbc32e4a 100644 --- a/src/lib/intmath/addsub.h +++ b/src/lib/intmath/addsub.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file addsub.h + * + * \brief Header for addsub.c + **/ + #ifndef TOR_INTMATH_ADDSUB_H #define TOR_INTMATH_ADDSUB_H diff --git a/src/lib/intmath/bits.c b/src/lib/intmath/bits.c index 85d901f71..4b5729e99 100644 --- a/src/lib/intmath/bits.c +++ b/src/lib/intmath/bits.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file bits.c + * + * \brief Count the bits in an integer, manipulate powers of 2, etc. + **/ + #include "lib/intmath/bits.h" /** Returns floor(log2(u64)). If u64 is 0, (incorrectly) returns 0. */ diff --git a/src/lib/intmath/bits.h b/src/lib/intmath/bits.h index 70f855089..80eebe935 100644 --- a/src/lib/intmath/bits.h +++ b/src/lib/intmath/bits.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file bits.h + * + * \brief Header for bits.c + **/ + #ifndef TOR_INTMATH_BITS_H #define TOR_INTMATH_BITS_H diff --git a/src/lib/intmath/cmp.h b/src/lib/intmath/cmp.h index 627e5d18b..16952bee3 100644 --- a/src/lib/intmath/cmp.h +++ b/src/lib/intmath/cmp.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file cmp.h + * + * \brief Macro definitions for MIN, MAX, and CLAMP. + **/ + #ifndef TOR_INTMATH_CMP_H #define TOR_INTMATH_CMP_H diff --git a/src/lib/intmath/logic.h b/src/lib/intmath/logic.h index 0510a621d..b3eabc652 100644 --- a/src/lib/intmath/logic.h +++ b/src/lib/intmath/logic.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file logic.h + * + * \brief Macros for comparing the boolean value of integers. + **/ + #ifndef HAVE_TOR_LOGIC_H #define HAVE_TOR_LOGIC_H diff --git a/src/lib/intmath/muldiv.c b/src/lib/intmath/muldiv.c index 3e627b237..c5fc689e2 100644 --- a/src/lib/intmath/muldiv.c +++ b/src/lib/intmath/muldiv.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file muldiv.c + * + * \brief Integer math related to multiplication, division, and rounding. + **/ + #include "lib/intmath/muldiv.h" #include "lib/err/torerr.h" diff --git a/src/lib/intmath/muldiv.h b/src/lib/intmath/muldiv.h index de76d9eb6..45b896922 100644 --- a/src/lib/intmath/muldiv.h +++ b/src/lib/intmath/muldiv.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file muldiv.h + * + * \brief Header for muldiv.c + **/ + #ifndef TOR_INTMATH_MULDIV_H #define TOR_INTMATH_MULDIV_H diff --git a/src/lib/intmath/weakrng.c b/src/lib/intmath/weakrng.c index 2ecab97cc..36cf5fb0a 100644 --- a/src/lib/intmath/weakrng.c +++ b/src/lib/intmath/weakrng.c @@ -3,6 +3,15 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file weakrng.c + * + * \brief A weak but fast PRNG based on a linear congruential generator. + * + * We don't want to use the platform random(), since some of them are even + * worse than this. + **/ + #include "lib/intmath/weakrng.h" #include "lib/err/torerr.h" diff --git a/src/lib/intmath/weakrng.h b/src/lib/intmath/weakrng.h index e5a88b30f..679bf2449 100644 --- a/src/lib/intmath/weakrng.h +++ b/src/lib/intmath/weakrng.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file weakrng.h + * + * \brief Header for weakrng.c + **/ + #ifndef TOR_WEAKRNG_H #define TOR_WEAKRNG_H diff --git a/src/lib/lock/compat_mutex.c b/src/lib/lock/compat_mutex.c index e0f6224a8..bfab6dd29 100644 --- a/src/lib/lock/compat_mutex.c +++ b/src/lib/lock/compat_mutex.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_mutex.c + * + * \brief Portable wrapper for platform mutex implementations. + **/ + #include "lib/lock/compat_mutex.h" #include "lib/malloc/util_malloc.h" diff --git a/src/lib/lock/compat_mutex.h b/src/lib/lock/compat_mutex.h index 92978086a..f467aa5db 100644 --- a/src/lib/lock/compat_mutex.h +++ b/src/lib/lock/compat_mutex.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_mutex.h + * + * \brief Header for compat_mutex.c + **/ + #ifndef TOR_COMPAT_MUTEX_H #define TOR_COMPAT_MUTEX_H diff --git a/src/lib/lock/compat_mutex_pthreads.c b/src/lib/lock/compat_mutex_pthreads.c index 390da4fb8..983abf5ae 100644 --- a/src/lib/lock/compat_mutex_pthreads.c +++ b/src/lib/lock/compat_mutex_pthreads.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_mutex_pthreads.c + * + * \brief Implement the tor_mutex API using pthread_mutex_t. + **/ + #include "lib/lock/compat_mutex.h" #include "lib/cc/compat_compiler.h" #include "lib/err/torerr.h" diff --git a/src/lib/lock/compat_mutex_winthreads.c b/src/lib/lock/compat_mutex_winthreads.c index 32be288c7..22c1edeed 100644 --- a/src/lib/lock/compat_mutex_winthreads.c +++ b/src/lib/lock/compat_mutex_winthreads.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_mutex_winthreads.c + * + * \brief Implement the tor_mutex API using CRITICAL_SECTION. + **/ + #include "lib/lock/compat_mutex.h" #include "lib/err/torerr.h" diff --git a/src/lib/math/fp.c b/src/lib/math/fp.c index d1c442825..d5989db63 100644 --- a/src/lib/math/fp.c +++ b/src/lib/math/fp.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file fp.c + * + * \brief Basic floating-point compatibility and convenience code. + **/ + #include "orconfig.h" #include "lib/math/fp.h" diff --git a/src/lib/math/fp.h b/src/lib/math/fp.h index b35c18a1c..e27b8f8d8 100644 --- a/src/lib/math/fp.h +++ b/src/lib/math/fp.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file fp.h + * + * \brief Header for fp.c + **/ + #ifndef TOR_FP_H #define TOR_FP_H diff --git a/src/lib/math/laplace.c b/src/lib/math/laplace.c index 8e45a1fb3..6b33b4690 100644 --- a/src/lib/math/laplace.c +++ b/src/lib/math/laplace.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file laplace.c + * + * \brief Implements a Laplace distribution, used for adding noise to things. + **/ + #include "orconfig.h" #include "lib/math/laplace.h" #include "lib/math/fp.h" diff --git a/src/lib/math/laplace.h b/src/lib/math/laplace.h index b22862e64..62d698e36 100644 --- a/src/lib/math/laplace.h +++ b/src/lib/math/laplace.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file laplace.h + * + * \brief Header for laplace.c + **/ + #ifndef TOR_LAPLACE_H #define TOR_LAPLACE_H diff --git a/src/lib/memarea/memarea.c b/src/lib/memarea/memarea.c index 7fe382572..2d510a51a 100644 --- a/src/lib/memarea/memarea.c +++ b/src/lib/memarea/memarea.c @@ -1,7 +1,9 @@ /* Copyright (c) 2008-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ -/** \file memarea.c +/** + * \file memarea.c + * * \brief Implementation for memarea_t, an allocator for allocating lots of * small objects that will be freed all at once. */ diff --git a/src/lib/memarea/memarea.h b/src/lib/memarea/memarea.h index e52f5a1be..4978b5416 100644 --- a/src/lib/memarea/memarea.h +++ b/src/lib/memarea/memarea.h @@ -1,6 +1,11 @@ /* Copyright (c) 2008-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ -/* Tor dependencies */ + +/** + * \file memarea.h + * + * \brief Header for memarea.c + **/ #ifndef TOR_MEMAREA_H #define TOR_MEMAREA_H diff --git a/src/lib/meminfo/meminfo.c b/src/lib/meminfo/meminfo.c index 34b4ad3b5..b5a74ce62 100644 --- a/src/lib/meminfo/meminfo.c +++ b/src/lib/meminfo/meminfo.c @@ -3,6 +3,13 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file meminfo.c + * + * \brief Functions to query total memory, and access meta-information about + * the allocator. + **/ + #include "lib/meminfo/meminfo.h" #include "lib/cc/compat_compiler.h" diff --git a/src/lib/meminfo/meminfo.h b/src/lib/meminfo/meminfo.h index a970e992f..b67d23555 100644 --- a/src/lib/meminfo/meminfo.h +++ b/src/lib/meminfo/meminfo.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file meminfo.h + * + * \brief Header for meminfo.c + **/ + #ifndef TOR_MEMINFO_H #define TOR_MEMINFO_H diff --git a/src/lib/net/alertsock.c b/src/lib/net/alertsock.c index c6ea1551f..340f9513f 100644 --- a/src/lib/net/alertsock.c +++ b/src/lib/net/alertsock.c @@ -3,6 +3,17 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file alertsock.c + * + * \brief Use a socket to alert the main thread from a worker thread. + * + * Because our main loop spends all of its time in select, epoll, kqueue, or + * etc, we need a way to wake up the main loop from another thread. This code + * tries to provide the fastest reasonable way to do that, depending on our + * platform. + **/ + #include "orconfig.h" #include "lib/net/alertsock.h" #include "lib/net/socket.h" diff --git a/src/lib/net/alertsock.h b/src/lib/net/alertsock.h index 026a15cad..5dfe53a2a 100644 --- a/src/lib/net/alertsock.h +++ b/src/lib/net/alertsock.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file alertsock.h + * + * \brief Header for alertsock.c + **/ + #ifndef TOR_ALERTSOCK_H #define TOR_ALERTSOCK_H diff --git a/src/lib/net/buffers_net.h b/src/lib/net/buffers_net.h index d03b61376..417f6f941 100644 --- a/src/lib/net/buffers_net.h +++ b/src/lib/net/buffers_net.h @@ -5,8 +5,9 @@ /* See LICENSE for licensing information */ /** - * \file buffers.h - * \brief Header file for buffers.c. + * \file buffers_net.h + * + * \brief Header file for buffers_net.c. **/ #ifndef TOR_BUFFERS_NET_H
participants (1)
-
nickm＠torproject.org