[tor-commits] [tor/master] File-level documentation for some of src/lib.

2 Jul 2018

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

    

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

[tor-commits] [tor/master] File-level documentation for some of src/lib.