File-level documentation for some of src/lib.

diff --git a/src/lib/arch/bytes.h b/src/lib/arch/bytes.h
index 4359b0f72388149dc74f66d1dd89aa0d33b96ed9..a2e2224d3c307f5fa6156c977c00043da310d88f 100644 (file)
--- 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 55b15402f252eae9f2a71f618a2b4d9f48fff750..5d536e78b54c342f7ff33ef350c9066210b6a2ba 100644 (file)
--- 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 2cb5dbaec2017db5054bb4a42431bdac56994e6c..e87e788f14e141c1ee7c2211cd05ac026b6b798a 100644 (file)
--- 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 4b887723825ca67724f05aefe9babf5c6c804ad9..63ee9e01029b2feecf65e89fc5ca2ee110c4aa94 100644 (file)
--- 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 2cea433fb03586c04dbc14ac51f6d86d2c1897a4..172d56cc0652a3022896f95e90f1e30c3f44eacf 100644 (file)
--- 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 577acf5e4891a422279fb707f94bf957d7aa9661..14f909cb19a751727e5033fe5c1a20e8fa6d1a01 100644 (file)
--- 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 0e98033bfd5d13f0835b53f8b3f456f670b0de8a..5849704e3550f87f5a4fafc2b5580751d85ead01 100644 (file)
--- 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 8b16fb298b73183a2006d2a482acc075a07fd850..c48f83cfc72dd04500f867f1848a892035e8cf32 100644 (file)
--- 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 3d84356cc8b6e9cd9d35104891b7e6bc899cd2a9..0602eac89101952e9de0c49a75d0e2ea22edabca 100644 (file)
--- 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 ac21c287182fa0272973937973146f5dcf451f62..ff71622682fed52fa4d893208d38e9bbacc25779 100644 (file)
--- 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 bd23750d546ee163a7437bc9e75a105c849f278f..f0675f347b3ddd1692bdd1412cf1549a0fc3ea1c 100644 (file)
--- 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 9025cab9f614a11e5449f2595d0d9ab3eb6559ad..63c50e045d3739ab4621491bdd689c01186f84b6 100644 (file)
--- 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 76ecbda0a283f55be0789ef444cab702086a6c36..3b19cbfce499ddd1fd700e0c0d2cc8942a8df3a2 100644 (file)
--- 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 9ed35a150e83f9eadabab4825889017b8f581a8e..00fabd09138427b8d776ad41e7f50dc10a4f442b 100644 (file)
--- 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 b270897b6888c817d709045eeca8da2acbb5e417..2429185b52ec637c1ca5593b61911cb5d949b4ad 100644 (file)
--- 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 f426fff20d6d2357b2826e0e3aacd69b81422605..dd772cae074de4b17b076fed3f59e94af74a5a97 100644 (file)
--- 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 67f9eb0e870e4264426b2eb54b12c463a3448267..23cbaa7070a220da7d5de3617964e020d6dd8731 100644 (file)
--- 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 7f535b321ab61ef60c8a6d1fa4068a7c079bb298..3486b6a82ba43b265718f2e3322608234dec6dfa 100644 (file)
--- 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 f03faed5eb8937e90769723209eef7c254d09ac8..41f1200947881ab1fb69c024156ffb628bb92318 100644 (file)
--- 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 86c17f0d2cbb5890228ebae10726c0d94092bd65..994a52e70cd02c9de44cf28944527c78205b5172 100644 (file)
--- 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 3dff5e7f7f14c0815c725b4934a3485e213feba3..2da109d958944e5385653e20748a97e7fed07af1 100644 (file)
--- 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 cffd6f6dbc32b30273a2a77fdb2da9dd501fde99..53ee776fe78db4f7e6f117d8b23607e04ba4308f 100644 (file)
--- 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 74585552078c925c36ca9e27bbe49ae3c0c2dfae..8bf0797627bdda9b5c373bd3675a375523b1189b 100644 (file)
--- 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 ef60f17e3671c2fedd2f77fe49e2458cde5fb5b3..ea9c8e9fd10a6810fbe2d6367c934f807d7861bf 100644 (file)
--- 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 41508ce5e6eccdb185ef3a2f8cd677fd8267130f..2892442adf164846f24277e4529ce92be561567c 100644 (file)
--- 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 cded6459f7a9174fd448db8e05afacdff72db562..5f5ecd3c37f7b67933e01b6106aff195612e1bc6 100644 (file)
--- 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 7f77428436b0b1b8503227a69ea0b0ae7c8abd02..70c43484f59f0bb9b369c6e919a240d1c3c91856 100644 (file)
--- 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 8d8f694f1d4271f317c10e653f36dfe84d82b6b6..f9e139f967b616d86ce422849d268fab5d7c1dc3 100644 (file)
--- 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 21577e1845dcafeba8bac453339f1adc25013fab..afb57e03dd619846a8a059697e1dd81ec068c684 100644 (file)
--- 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 0fb3ed1e620e6dcb08bf8aea27083798487ea90c..c8f05455b7b0bfffb0c51811989dcf0b89620c75 100644 (file)
--- 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 37bd9f0368edfd478f8f574d0d1bf58a017d60fb..600c7f6b703e993d2e473547dda22f9452e89983 100644 (file)
--- 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 bd8250b00241d9f6855311bbf9ecfba15e456ce8..a926f4ac059d5e96f669867fc49db0022ef6c67a 100644 (file)
--- 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 9f09327d841246215ea539e336cf8761862ddb5d..cc339f747e19a8b4b75f77b33d2f94cf9d9afe29 100644 (file)
--- 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 925211fbd6fa6e2e4f15071cf85ecb94cc7d8fc9..61a04e6d58848f7aa64240640f6b9b6eda237176 100644 (file)
--- 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 0335f6dc594c5dd11f91cb14e02d4e85bebcdca3..4e0a398baa993a1dd0f8025847d0303fdd14e488 100644 (file)
--- 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 be4ec485f1a7f76defbf17e3470bc667f11c6208..5a12eb821582288b9c86e748dc4d153b7dc34128 100644 (file)
--- 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 926b17dbdef3c7504635c3a2a959b6e7e8f801de..2dbba3c5f8527f9412157c78dc147344d949cded 100644 (file)
--- 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 3fc9cd4264c59e0bd6dcbab48b6dddcc948b16fb..972fd5658d422d459c4763014c9eb5586d272c05 100644 (file)
--- 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 1c5bb023b553bfb9909addb4272c2948d8fc5cf0..e26349811c535c35a223bf2e01eb13deec8012f7 100644 (file)
--- 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 6d69fd5e780555110c8948bd02ae4e1cd98139e9..2d758c1b5f942b671852c9f2f3af2295561c7698 100644 (file)
--- 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 b0585775f5dcf5a81822c2797f5474631720115d..125f368802f08342fd99eae0fbb29d481e67c9a2 100644 (file)
--- 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 68cda677659275f93c4b0c42540994d031e028c5..708ff0505a7af0c58a6c04a29b91a39885c70f7f 100644 (file)
--- 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 a3073a99ec5e6c6521d5ad132a0a50a55be136d8..384d1f514fd86bacbf5f32e2bb002976d664e200 100644 (file)
--- 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 d013e4550d61bbc280149d2001a5a6adc731a50c..1cda2374d8526255bc2375b2c007bae4ce7b8919 100644 (file)
--- 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 1ecb1c0a1199ae1eee1ef132884bd8deec9223b2..58594b46343277e9f0e6018169615abfdf9c54ed 100644 (file)
--- 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 b7abbc7813740abf457a8210745d49b269b3252c..3d7a9da59d9ca4f1eada928961465bf426a58371 100644 (file)
--- 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 31c891ede80f6d54a45a7eebe1cc53e73e30b4bd..3b3ab6ed2b633c4c40cb2005520fcff7e22cfd65 100644 (file)
--- 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 7a88a841a662065078e38fd5fe46f35018ffece8..532807c03f5a22eb897bcd9262e971508c9b992d 100644 (file)
--- 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 f53f046451e0896582188dddc2c5db3f014aaf69..5b10b9b78d08c103e12b680444044683a629266f 100644 (file)
--- 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 816c5a2bd704d331013d0e01cfd783d83176a33b..fcfdca68223f6dbf57136492e7180c2011d9173c 100644 (file)
--- 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 5277adfa49f23a93b9ef97199b849621e2e6c1c8..5bbc32e4a978d7bbd612a421fa7080198241dc64 100644 (file)
--- 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 85d901f71b39eeda6b248d882fac0f0a9d81749c..4b5729e99af0c554a49d65fb5619613069974c70 100644 (file)
--- 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 70f855089c3d0fe8139a94f9713e27cef38936c7..80eebe93589fe613d90990e7e8737bcdbcf85f48 100644 (file)
--- 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 627e5d18b436c9490af7349dd4e9ba1056853d11..16952bee3e6adc2517aee3606236a9f379333591 100644 (file)
--- 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 0510a621dc6a2581b5a49ad4e2abf5714c916b31..b3eabc652eb623be75a1046f32c2540ec8906e17 100644 (file)
--- 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 3e627b237aed586a00525d466f320768e1898a6e..c5fc689e2d5b2fbafd88efbdf2ccf91919e46464 100644 (file)
--- 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 de76d9eb68940ab4807c75a920770f00f6b95fbb..45b896922fc8fb08735316822716cf4b6d2fbbc0 100644 (file)
--- 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 2ecab97cc1775bf770232b85f0b7e406ed85a5cd..36cf5fb0aa9d6989bf4e5c38c22599f1b35f7864 100644 (file)
--- 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 e5a88b30fec9fbb00e1434bbec16d02925133527..679bf2449c1e48a67c224dd4bbb711cc3cd6b62e 100644 (file)
--- 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 e0f6224a8316669a6de6d63b3faf5161232dd01f..bfab6dd29b91f3d549c5d5aee3f013a759dec34f 100644 (file)
--- 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 92978086aca73020ae9368bc7fb0de5fbabc63f4..f467aa5dba1f043a1a0873fbb085dfb71e21052c 100644 (file)
--- 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 390da4fb819f3b44b865cb5188890e0de56dc9ad..983abf5ae5361332dd916249fffedc7ba56db099 100644 (file)
--- 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 32be288c7fa7dffefb8ba6b161646ca954a2ce13..22c1edeed4259bb844f2f15b620e80128ffccf12 100644 (file)
--- 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 d1c442825174dffdb654ca533ed87cc4110cbebd..d5989db6372fc47bf1a3c62a4bc8eb1c5c5426de 100644 (file)
--- 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 b35c18a1c790eafe6a24008911ed41e2e80e1cbf..e27b8f8d80e092a3b0ca8125cdc335c66bbade51 100644 (file)
--- 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 8e45a1fb33e37b5c6860b6acf7a92ccab305d92c..6b33b46902a5b32282dbf2232f04bdad9e977e91 100644 (file)
--- 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 b22862e64ae0354e36a86b4abb67397565b133be..62d698e3690deb8428f02d1e083ba60c346c1239 100644 (file)
--- 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 7fe3825723075f6b6a69ed0c20ffbca174c81b6e..2d510a51ac09fc745019ace66e8e277b7bd36b8f 100644 (file)
--- 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 e52f5a1be79d72e78873510a402c5754175e8085..4978b541625aa19208bfdc0c98049dbbb46c9776 100644 (file)
--- 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 34b4ad3b5d4e374c97be55e0cc5d7da2beccb491..b5a74ce6246f517e3de3f4dba810b83f9b31c7a9 100644 (file)
--- 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 a970e992f0c36ef19fc07a4a111daf567ae89e8b..b67d2355595f12a4144e91442c4affc9845e26d4 100644 (file)
--- 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 c6ea1551f83ab4f782d2b058758910651efb4b87..340f9513fbb20f6fd459ca20ddc7e7b2fe688090 100644 (file)
--- 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 026a15cad0bc933a56e8e6567e9725e0fa338816..5dfe53a2a0bcd02b4badb72c7686c497e58e2593 100644 (file)
--- 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 d03b61376e6637e10ef67a5f8b8b44bab4ba0b04..417f6f9413ab3208465feece9b868287fb2a5af1 100644 (file)
--- 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