File-level documentation for some of src/lib.

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"
 

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) */
-

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"

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"

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"

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"

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

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);

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.
  **/
 

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"
 

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"
 

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"

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"

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_) */
-

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) */
-

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

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
 

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"

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
 

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"

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
 

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"

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
 

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"

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
 

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"

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"
 

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"

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

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
 

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"

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;
 

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"

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"
 

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

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
 

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"
 

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"

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
 

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"

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
 

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"

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
 

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"

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
 

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

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
 

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"
 

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
 

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"
 

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
 

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. */

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
 

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
 

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
 

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"
 

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
 

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"
 

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
 

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"
 

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
 

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"

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"
 

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"
 

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
 

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"

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
 

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.
  */

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

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"

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
 

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"

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
 

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