commit 4f42c923d61655235ebbae82f64106ecff9458d7 parent 4793d913503f9349ca4b57d77a47bd1bbceecfe5 Author: Nick Mathewson <nickm@torproject.org> Date: Tue, 10 Jul 2018 12:22:01 -0400 File-level summary documentation for src/lib/*/*.[ch] Diffstat:
84 files changed, 428 insertions(+), 27 deletions(-)
diff --git a/src/lib/cc/compat_compiler.h b/src/lib/cc/compat_compiler.h @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_compiler.h + * \brief Utility macros to handle different features and behavior in different + * compilers. + **/ + #ifndef TOR_COMPAT_COMPILER_H #define TOR_COMPAT_COMPILER_H diff --git a/src/lib/cc/torint.h b/src/lib/cc/torint.h @@ -5,18 +5,13 @@ /** * \file torint.h - * \brief Header file to define uint32_t and friends + * + * \brief Integer definitions used throughout Tor. **/ #ifndef TOR_TORINT_H #define TOR_TORINT_H -/** - * \file torint.h - * - * \brief Integer definitions used throughout Tor. - **/ - #include "orconfig.h" #include <stdint.h> diff --git a/src/lib/crypt_ops/crypto_curve25519.h b/src/lib/crypt_ops/crypto_curve25519.h @@ -1,6 +1,11 @@ /* Copyright (c) 2012-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file crypto_curve25519.h + * \brief Header for crypto_curve25519.c + **/ + #ifndef TOR_CRYPTO_CURVE25519_H #define TOR_CRYPTO_CURVE25519_H diff --git a/src/lib/crypt_ops/crypto_ed25519.h b/src/lib/crypt_ops/crypto_ed25519.h @@ -1,6 +1,11 @@ /* Copyright (c) 2012-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file crypto_ed25519.h + * \brief Header for crypto_ed25519.c + **/ + #ifndef TOR_CRYPTO_ED25519_H #define TOR_CRYPTO_ED25519_H diff --git a/src/lib/crypt_ops/crypto_format.h b/src/lib/crypt_ops/crypto_format.h @@ -4,6 +4,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file crypto_format.h + * \brief Header for crypto_format.c + **/ + #ifndef TOR_CRYPTO_FORMAT_H #define TOR_CRYPTO_FORMAT_H diff --git a/src/lib/crypt_ops/crypto_openssl_mgt.c b/src/lib/crypt_ops/crypto_openssl_mgt.c @@ -5,7 +5,7 @@ /* See LICENSE for licensing information */ /** - * \file crypto_openssl.c + * \file crypto_openssl_mgt.c * * \brief Block of functions related to operations from OpenSSL. **/ diff --git a/src/lib/crypt_ops/crypto_openssl_mgt.h b/src/lib/crypt_ops/crypto_openssl_mgt.h @@ -5,9 +5,9 @@ /* See LICENSE for licensing information */ /** - * \file crypto_openssl.h + * \file crypto_openssl_mgt.h * - * \brief Headers for crypto_openssl.c + * \brief Headers for crypto_openssl_mgt.c **/ #ifndef TOR_CRYPTO_OPENSSL_H diff --git a/src/lib/defs/dh_sizes.h b/src/lib/defs/dh_sizes.h @@ -4,6 +4,15 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file dh_sizes.h + + * \brief Definitions for sizes of Diffie-Hellman groups elements in Z_p. + * + * Tor uses these definitions throughout its codebase, even in parts that + * don't actually do any Diffie-Hellman calculations. + **/ + #ifndef TOR_DH_SIZES_H #define TOR_DH_SIZES_H diff --git a/src/lib/defs/x25519_sizes.h b/src/lib/defs/x25519_sizes.h @@ -4,6 +4,15 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file x25519_sizes.h + + * \brief Definitions for sizes of x25519 keys and elements. + * + * Tor uses these definitions throughout its codebase, even in parts that + * don't actually do any x25519 calculations. + **/ + #ifndef TOR_X25519_SIZES_H #define TOR_X25519_SIZES_H diff --git a/src/lib/evloop/compat_libevent.h b/src/lib/evloop/compat_libevent.h @@ -1,6 +1,11 @@ /* Copyright (c) 2009-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_libevent.h + * \brief Header for compat_libevent.c + **/ + #ifndef TOR_COMPAT_LIBEVENT_H #define TOR_COMPAT_LIBEVENT_H diff --git a/src/lib/evloop/timers.h b/src/lib/evloop/timers.h @@ -1,6 +1,11 @@ /* Copyright (c) 2016-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file timers.h + * \brief Header for timers.c + **/ + #ifndef TOR_TIMERS_H #define TOR_TIMERS_H @@ -28,4 +33,3 @@ STATIC void timers_run_pending(void); #endif #endif /* !defined(TOR_TIMERS_H) */ - diff --git a/src/lib/evloop/token_bucket.h b/src/lib/evloop/token_bucket.h @@ -2,8 +2,8 @@ /* See LICENSE for licensing information */ /** - * \file token_bucket_rw.h - * \brief Headers for token_bucket_rw.c + * \file token_bucket.h + * \brief Headers for token_bucket.c **/ #ifndef TOR_TOKEN_BUCKET_H @@ -115,4 +115,3 @@ STATIC uint32_t rate_per_sec_to_rate_per_step(uint32_t rate); #endif #endif /* TOR_TOKEN_BUCKET_H */ - diff --git a/src/lib/evloop/workqueue.h b/src/lib/evloop/workqueue.h @@ -1,6 +1,11 @@ /* Copyright (c) 2013-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file workqueue.h + * \brief Header for workqueue.c + **/ + #ifndef TOR_WORKQUEUE_H #define TOR_WORKQUEUE_H diff --git a/src/lib/log/escape.c b/src/lib/log/escape.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file escape.c + * \brief Escape untrusted strings before sending them to the log. + **/ + #include "lib/log/escape.h" #include "lib/log/util_bug.h" #include "lib/string/compat_ctype.h" diff --git a/src/lib/log/escape.h b/src/lib/log/escape.h @@ -4,6 +4,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file escape.h + * \brief Header for escape.c + **/ + #ifndef TOR_ESCAPE_H #define TOR_ESCAPE_H diff --git a/src/lib/log/ratelim.c b/src/lib/log/ratelim.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ratelim.c + * \brief Summarize similar messages that would otherwise flood the logs. + **/ + #include "lib/log/ratelim.h" #include "lib/malloc/util_malloc.h" #include "lib/string/printf.h" diff --git a/src/lib/log/ratelim.h b/src/lib/log/ratelim.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ratelim.h + * \brief Summarize similar messages that would otherwise flood the logs. + **/ + #ifndef TOR_RATELIM_H #define TOR_RATELIM_H diff --git a/src/lib/log/win32err.c b/src/lib/log/win32err.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file win32err.c + * \brief Convert windows error codes to useful C strings. + **/ + #ifdef _WIN32 #include "orconfig.h" #include "lib/log/win32err.h" diff --git a/src/lib/log/win32err.h b/src/lib/log/win32err.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file win32err.h + * \brief Header for win32err.c + **/ + #ifndef TOR_WIN32ERR_H #define TOR_WIN32ERR_H diff --git a/src/lib/net/buffers_net.c b/src/lib/net/buffers_net.c @@ -4,6 +4,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file buffers_net.c + * \brief Read and write data on a buf_t object. + **/ + #define BUFFERS_PRIVATE #include "lib/net/buffers_net.h" #include "lib/container/buffers.h" diff --git a/src/lib/net/gethostname.c b/src/lib/net/gethostname.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file gethostname.c + * \brief Mockable wrapper for gethostname(). + */ + #include "orconfig.h" #include "lib/net/gethostname.h" diff --git a/src/lib/net/gethostname.h b/src/lib/net/gethostname.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file gethostname.h + * \brief Header for gethostname.c + **/ + #ifndef TOR_GETHOSTNAME_H #define TOR_GETHOSTNAME_H diff --git a/src/lib/net/ipv4.c b/src/lib/net/ipv4.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ipv4.c + * \brief Functions for encoding and decoding IPv4 addresses into strings + **/ + #include "orconfig.h" #include "lib/cc/torint.h" #include "lib/net/ipv4.h" diff --git a/src/lib/net/ipv4.h b/src/lib/net/ipv4.h @@ -3,6 +3,10 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ipv4.h + * \brief Header for ipv4.c + **/ #ifndef TOR_IPV4_H #define TOR_IPV4_H diff --git a/src/lib/net/ipv6.c b/src/lib/net/ipv6.c @@ -3,6 +3,13 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ipv6.c + * \brief Functions for encoding and decoding IPv6 addresses + * + * (Because these functions are generic, they can also handle IPv4 addresses). + **/ + #include "lib/net/ipv6.h" #include "lib/net/ipv4.h" #include "lib/string/util_string.h" diff --git a/src/lib/net/ipv6.h b/src/lib/net/ipv6.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file ipv6.h + * \brief Header for ipv6.c + **/ + #ifndef TOR_IPV6_H #define TOR_IPV6_H diff --git a/src/lib/net/nettypes.h b/src/lib/net/nettypes.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file nettypes.h + * \brief Declarations for types used throughout the Tor networking system + **/ + #ifndef TOR_NET_TYPES_H #define TOR_NET_TYPES_H diff --git a/src/lib/net/resolve.c b/src/lib/net/resolve.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file resolve.c + * \brief Use the libc DNS resolver to convert hostnames into addresses. + **/ + #include "lib/net/resolve.h" #include "lib/net/address.h" #include "lib/malloc/util_malloc.h" diff --git a/src/lib/net/resolve.h b/src/lib/net/resolve.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file resolve.h + * \brief Header for resolve.c + **/ + #ifndef TOR_RESOLVE_H #define TOR_RESOLVE_H diff --git a/src/lib/net/socket.c b/src/lib/net/socket.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file socket.c + * \brief Compatibility and utility functions for working with network + * sockets. + **/ + #define SOCKET_PRIVATE #include "lib/net/socket.h" #include "lib/net/address.h" diff --git a/src/lib/net/socket.h b/src/lib/net/socket.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file socket.h + * \brief Header for socket.c + **/ + #ifndef TOR_SOCKET_H #define TOR_SOCKET_H diff --git a/src/lib/net/socks5_status.h b/src/lib/net/socks5_status.h @@ -3,6 +3,16 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file socks5_status.h + * \brief Status codes used by the SOCKS5 protocol. + **/ + +/* NOTE: it probably isn't necessary to put this header in lib/net, but + * we need it in _some_ lower-level layer for now, since it is used by + * tools/tor-resolve.c. + */ + #ifndef TOR_SOCKS5_STATUS_H #define TOR_SOCKS5_STATUS_H diff --git a/src/lib/osinfo/uname.c b/src/lib/osinfo/uname.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file uname.c + * \brief Look up a description of the operating system. + **/ + #include "orconfig.h" #include "lib/osinfo/uname.h" diff --git a/src/lib/osinfo/uname.h b/src/lib/osinfo/uname.h @@ -1,3 +1,12 @@ +/* Copyright (c) 2003-2004, Roger Dingledine + * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson. + * Copyright (c) 2007-2018, The Tor Project, Inc. */ +/* See LICENSE for licensing information */ + +/** + * \file uname.h + * \brief Header for uname.c + **/ #ifndef HAVE_TOR_UNAME_H #define HAVE_TOR_UNAME_H diff --git a/src/lib/process/daemon.c b/src/lib/process/daemon.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file daemon.c + * \brief Run the tor process in the background (unix only) + **/ + #include "orconfig.h" #include "lib/process/daemon.h" diff --git a/src/lib/process/daemon.h b/src/lib/process/daemon.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file daemon.h + * \brief Header for daemon.c + **/ + #ifndef TOR_DAEMON_H #define TOR_DAEMON_H diff --git a/src/lib/process/env.c b/src/lib/process/env.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file env.c + * \brief Inspect and manipulate the environment variables. + **/ + #include "orconfig.h" #include "lib/process/env.h" diff --git a/src/lib/process/env.h b/src/lib/process/env.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file env.h + * \brief Header for env.c + **/ + #ifndef TOR_ENV_H #define TOR_ENV_H diff --git a/src/lib/process/pidfile.c b/src/lib/process/pidfile.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file pidfile.c + * \brief Record this process's PID to disk. + **/ + #include "orconfig.h" #include "lib/process/pidfile.h" diff --git a/src/lib/process/pidfile.h b/src/lib/process/pidfile.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file pidfile.h + * \brief Header for pidfile.c + **/ + #ifndef TOR_PIDFILE_H #define TOR_PIDFILE_H diff --git a/src/lib/process/restrict.c b/src/lib/process/restrict.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file restrict.c + * \brief Drop privileges from the current process. + **/ + #include "orconfig.h" #include "lib/process/restrict.h" #include "lib/intmath/cmp.h" diff --git a/src/lib/process/restrict.h b/src/lib/process/restrict.h @@ -4,8 +4,8 @@ /* See LICENSE for licensing information */ /** - * \file waitpid.h - * \brief Headers for waitpid.c + * \file restrict.h + * \brief Header for restrict.c **/ #ifndef TOR_RESTRICT_H diff --git a/src/lib/process/setuid.c b/src/lib/process/setuid.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file setuid.c + * \brief Change the user ID after Tor has started (Unix only) + **/ + #include "orconfig.h" #include "lib/process/setuid.h" diff --git a/src/lib/process/setuid.h b/src/lib/process/setuid.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file setuid.h + * \brief Header for setuid.c + **/ + #ifndef TOR_SETUID_H #define TOR_SETUID_H diff --git a/src/lib/process/subprocess.c b/src/lib/process/subprocess.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file subprocess.c + * \brief Launch and monitor other processes. + **/ + #define SUBPROCESS_PRIVATE #include "lib/process/subprocess.h" diff --git a/src/lib/process/subprocess.h b/src/lib/process/subprocess.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file subprocess.h + * \brief Header for subprocess.c + **/ + #ifndef TOR_SUBPROCESS_H #define TOR_SUBPROCESS_H diff --git a/src/lib/process/waitpid.c b/src/lib/process/waitpid.c @@ -4,10 +4,8 @@ /* See LICENSE for licensing information */ /** - * \file util_process.c - * \brief utility functions for launching processes and checking their - * status. These functions are kept separately from procmon so that they - * won't require linking against libevent. + * \file waitpid.c + * \brief Convenience structures for handlers for handling waitpid(). **/ #include "orconfig.h" diff --git a/src/lib/smartlist_core/smartlist_core.h b/src/lib/smartlist_core/smartlist_core.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file smartlist_core.h + * \brief Top-level declarations for the smartlist_t dynamic array type. + **/ + #ifndef TOR_SMARTLIST_CORE_H #define TOR_SMARTLIST_CORE_H diff --git a/src/lib/smartlist_core/smartlist_foreach.h b/src/lib/smartlist_core/smartlist_foreach.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file smartlist_foreach.h + * \brief Macros for iterating over the elements of a smartlist_t. + **/ + #ifndef TOR_SMARTLIST_FOREACH_H #define TOR_SMARTLIST_FOREACH_H diff --git a/src/lib/smartlist_core/smartlist_split.c b/src/lib/smartlist_core/smartlist_split.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file smartlist_split.c + * \brief Split a string into a smartlist_t of substrings. + **/ + #include "lib/smartlist_core/smartlist_core.h" #include "lib/smartlist_core/smartlist_split.h" diff --git a/src/lib/smartlist_core/smartlist_split.h b/src/lib/smartlist_core/smartlist_split.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file smartlist_split.h + * \brief Header for smartlist_split.c + **/ + #ifndef TOR_SMARTLIST_SPLIT_H #define TOR_SMARTLIST_SPLIT_H diff --git a/src/lib/string/compat_ctype.c b/src/lib/string/compat_ctype.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_ctype.c + * \brief Locale-independent character-type inspection (backend) + **/ + #include "lib/string/compat_ctype.h" /** diff --git a/src/lib/string/compat_ctype.h b/src/lib/string/compat_ctype.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_ctype.h + * \brief Locale-independent character-type inspection (header) + **/ + #ifndef TOR_COMPAT_CTYPE_H #define TOR_COMPAT_CTYPE_H diff --git a/src/lib/string/compat_string.c b/src/lib/string/compat_string.c @@ -3,6 +3,12 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_string.c + * \brief Useful string-processing functions that some platforms don't + * provide. + **/ + #include "lib/string/compat_string.h" #include "lib/err/torerr.h" diff --git a/src/lib/string/compat_string.h b/src/lib/string/compat_string.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file compat_string.h + * \brief Header for compat_string.c + **/ + #ifndef TOR_COMPAT_STRING_H #define TOR_COMPAT_STRING_H diff --git a/src/lib/string/parse_int.c b/src/lib/string/parse_int.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file parse_int.c + * \brief Convert strings into the integers they encode, with bounds checking. + **/ + #include "lib/string/parse_int.h" #include <errno.h> diff --git a/src/lib/string/parse_int.h b/src/lib/string/parse_int.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file parse_int.h + * \brief Header for parse_int.c + **/ + #ifndef TOR_PARSE_INT_H #define TOR_PARSE_INT_H diff --git a/src/lib/string/printf.c b/src/lib/string/printf.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file printf.c + * \brief Compatibility wrappers around snprintf and its friends + **/ + #include "lib/string/printf.h" #include "lib/err/torerr.h" #include "lib/cc/torint.h" diff --git a/src/lib/string/printf.h b/src/lib/string/printf.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file printf.h + * \brief Header for printf.c + **/ + #ifndef TOR_UTIL_PRINTF_H #define TOR_UTIL_PRINTF_H diff --git a/src/lib/string/scanf.c b/src/lib/string/scanf.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file scanf.c + * \brief Locale-independent minimal implementation of sscanf(). + **/ + #include "lib/string/scanf.h" #include "lib/string/compat_ctype.h" #include "lib/cc/torint.h" diff --git a/src/lib/string/scanf.h b/src/lib/string/scanf.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file scanf.h + * \brief Header for scanf.c + **/ + #ifndef TOR_UTIL_SCANF_H #define TOR_UTIL_SCANF_H diff --git a/src/lib/string/util_string.c b/src/lib/string/util_string.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file util_string.c + * \brief Non-standard string functions used throughout Tor. + **/ + #include "lib/string/util_string.h" #include "lib/string/compat_ctype.h" #include "lib/err/torerr.h" diff --git a/src/lib/string/util_string.h b/src/lib/string/util_string.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file util_string.h + * \brief Header for util_string.c + **/ + #ifndef TOR_UTIL_STRING_H #define TOR_UTIL_STRING_H diff --git a/src/lib/term/getpass.c b/src/lib/term/getpass.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file getpass.c + * \brief Cross-platform wrapper to read passphrases from the terminal. + **/ + #include "lib/term/getpass.h" #include "lib/log/util_bug.h" diff --git a/src/lib/term/getpass.h b/src/lib/term/getpass.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file getpass.h + * \brief Header for getpass.c + **/ + #ifndef TOR_GETPASS_H #define TOR_GETPASS_H diff --git a/src/lib/testsupport/testsupport.h b/src/lib/testsupport/testsupport.h @@ -1,10 +1,24 @@ /* Copyright (c) 2013-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file testsupport.h + * + * \brief Macros to implement mocking and selective exposure for the test code. + * + * Each Tor source file is built twice: once with TOR_UNIT_TESTS defined, and + * once with it undefined. The only difference between these configurations + * should be that when building for the tests, more functions are exposed as + * non-static, and a number of functions are declared as mockable. + **/ + #ifndef TOR_TESTSUPPORT_H #define TOR_TESTSUPPORT_H #ifdef TOR_UNIT_TESTS +/** The "STATIC" macro marks a function or variable that is static when + * building Tor for production, but non-static when building the unit + * tests. */ #define STATIC #define EXTERN(type, name) extern type name; #else @@ -87,4 +101,3 @@ /** @} */ #endif /* !defined(TOR_TESTSUPPORT_H) */ - diff --git a/src/lib/thread/numcpus.c b/src/lib/thread/numcpus.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file numcpus.c + * \brief Compute the number of CPUs configured on this system. + **/ + #include "orconfig.h" #include "lib/thread/numcpus.h" #include "lib/log/torlog.h" diff --git a/src/lib/thread/numcpus.h b/src/lib/thread/numcpus.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file numcpus.h + * \brief Header for numcpus.c + **/ + #ifndef TOR_NUMCPUS_H #define TOR_NUMCPUS_H diff --git a/src/lib/thread/threads.h b/src/lib/thread/threads.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file threads.h + * \brief Header for threads.c + **/ + #ifndef TOR_COMPAT_THREADS_H #define TOR_COMPAT_THREADS_H diff --git a/src/lib/time/tvdiff.c b/src/lib/time/tvdiff.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file tvdiff.c + * \brief Compute the difference between timevals, in various units. + **/ + #include "lib/time/tvdiff.h" #include "lib/cc/compat_compiler.h" diff --git a/src/lib/time/tvdiff.h b/src/lib/time/tvdiff.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file tvdiff.h + * \brief Header for tvdiff.c + **/ + #ifndef TOR_TVDIFF_H #define TOR_TVDIFF_H diff --git a/src/lib/tls/buffers_tls.c b/src/lib/tls/buffers_tls.c @@ -4,6 +4,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file buffers_tls.c + * \brief Read and write data on a tor_tls_t connection from a buf_t object. + **/ + #define BUFFERS_PRIVATE #include "orconfig.h" #include <stddef.h> diff --git a/src/lib/tls/buffers_tls.h b/src/lib/tls/buffers_tls.h @@ -4,6 +4,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file buffers_tls.h + * \brief Header for buffers_tls.c + **/ + #ifndef TOR_BUFFERS_TLS_H #define TOR_BUFFERS_TLS_H @@ -16,4 +21,3 @@ int buf_flush_to_tls(struct buf_t *buf, struct tor_tls_t *tls, size_t sz, size_t *buf_flushlen); #endif /* !defined(TOR_BUFFERS_TLS_H) */ - diff --git a/src/lib/trace/debug.h b/src/lib/trace/debug.h @@ -1,6 +1,11 @@ /* Copyright (c) 2017-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file debug.h + * \brief Macros for debugging our event-trace support. + **/ + #ifndef TOR_TRACE_LOG_DEBUG_H #define TOR_TRACE_LOG_DEBUG_H diff --git a/src/lib/trace/trace.c b/src/lib/trace/trace.c @@ -1,6 +1,13 @@ /* Copyright (c) 2017-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file trace.c + * \brief Common functions for event-tracing implementation + * + * See trace.h and doc/HACKING/Tracing.md for more information. + **/ + #include "lib/trace/trace.h" /** Initialize the tracing library. */ @@ -8,4 +15,3 @@ void tor_trace_init(void) { } - diff --git a/src/lib/trace/trace.h b/src/lib/trace/trace.h @@ -1,10 +1,14 @@ /* Copyright (c) 2017-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file trace.h + * \brief Header for trace.c + **/ + #ifndef TOR_TRACE_TRACE_H #define TOR_TRACE_TRACE_H void tor_trace_init(void); #endif // TOR_TRACE_TRACE_H - diff --git a/src/lib/wallclock/approx_time.c b/src/lib/wallclock/approx_time.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file approx_time.c + * \brief Cache the last result of time(), for performance and testing. + **/ + #include "orconfig.h" #include "lib/wallclock/approx_time.h" diff --git a/src/lib/wallclock/approx_time.h b/src/lib/wallclock/approx_time.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file approx_time.h + * \brief Header for approx_time.c + **/ + #ifndef TOR_APPROX_TIME_H #define TOR_APPROX_TIME_H diff --git a/src/lib/wallclock/timeval.c b/src/lib/wallclock/timeval.c diff --git a/src/lib/wallclock/timeval.h b/src/lib/wallclock/timeval.h @@ -3,6 +3,13 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file timeval.h + * + * \brief Declarations for timeval-related macros that some platforms + * are missing. + **/ + #ifndef TOR_TIMEVAL_H #define TOR_TIMEVAL_H diff --git a/src/lib/wallclock/tm_cvt.c b/src/lib/wallclock/tm_cvt.c @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file tm_cvt.c + * \brief Convert to and from struct tm, portably. + **/ + #include "orconfig.h" #include "lib/cc/torint.h" #include "lib/cc/compat_compiler.h" diff --git a/src/lib/wallclock/tm_cvt.h b/src/lib/wallclock/tm_cvt.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file tm_cvt.h + * \brief Header for tm_cvt.c + **/ + #ifndef TOR_WALLCLOCK_TM_CVT_H #define TOR_WALLCLOCK_TM_CVT_H diff --git a/src/lib/wallclock/tor_gettimeofday.c b/src/lib/wallclock/tor_gettimeofday.c @@ -4,9 +4,9 @@ /* See LICENSE for licensing information */ /** - * \file compat_time.c - * \brief Portable wrappers for finding out the current time, running - * timers, etc. + * \file tor_gettimeofday.c + * \brief Implementat gettimeofday() for windows, and other platforms without + * it. **/ #include "orconfig.h" diff --git a/src/lib/wallclock/tor_gettimeofday.h b/src/lib/wallclock/tor_gettimeofday.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2018, The Tor Project, Inc. */ /* See LICENSE for licensing information */ +/** + * \file tor_gettimeofday.h + * \brief Header for tor_gettimeofday.c + **/ + #ifndef TOR_GETTIMEOFDAY_H #define TOR_GETTIMEOFDAY_H