[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [tor/master] File-level summary documentation for src/lib/*/*.[ch]



commit 4f42c923d61655235ebbae82f64106ecff9458d7
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date:   Tue Jul 10 12:22:01 2018 -0400

    File-level summary documentation for src/lib/*/*.[ch]
---
 src/lib/cc/compat_compiler.h               |  6 ++++++
 src/lib/cc/torint.h                        |  9 ++-------
 src/lib/crypt_ops/crypto_curve25519.h      |  5 +++++
 src/lib/crypt_ops/crypto_ed25519.h         |  5 +++++
 src/lib/crypt_ops/crypto_format.h          |  5 +++++
 src/lib/crypt_ops/crypto_openssl_mgt.c     |  2 +-
 src/lib/crypt_ops/crypto_openssl_mgt.h     |  4 ++--
 src/lib/defs/dh_sizes.h                    |  9 +++++++++
 src/lib/defs/x25519_sizes.h                |  9 +++++++++
 src/lib/evloop/compat_libevent.h           |  5 +++++
 src/lib/evloop/timers.h                    |  6 +++++-
 src/lib/evloop/token_bucket.h              |  5 ++---
 src/lib/evloop/workqueue.h                 |  5 +++++
 src/lib/log/escape.c                       |  5 +++++
 src/lib/log/escape.h                       |  5 +++++
 src/lib/log/ratelim.c                      |  5 +++++
 src/lib/log/ratelim.h                      |  5 +++++
 src/lib/log/win32err.c                     |  5 +++++
 src/lib/log/win32err.h                     |  5 +++++
 src/lib/net/buffers_net.c                  |  5 +++++
 src/lib/net/gethostname.c                  |  5 +++++
 src/lib/net/gethostname.h                  |  5 +++++
 src/lib/net/ipv4.c                         |  5 +++++
 src/lib/net/ipv4.h                         |  4 ++++
 src/lib/net/ipv6.c                         |  7 +++++++
 src/lib/net/ipv6.h                         |  5 +++++
 src/lib/net/nettypes.h                     |  5 +++++
 src/lib/net/resolve.c                      |  5 +++++
 src/lib/net/resolve.h                      |  5 +++++
 src/lib/net/socket.c                       |  6 ++++++
 src/lib/net/socket.h                       |  5 +++++
 src/lib/net/socks5_status.h                | 10 ++++++++++
 src/lib/osinfo/uname.c                     |  5 +++++
 src/lib/osinfo/uname.h                     |  9 +++++++++
 src/lib/process/daemon.c                   |  5 +++++
 src/lib/process/daemon.h                   |  5 +++++
 src/lib/process/env.c                      |  5 +++++
 src/lib/process/env.h                      |  5 +++++
 src/lib/process/pidfile.c                  |  5 +++++
 src/lib/process/pidfile.h                  |  5 +++++
 src/lib/process/restrict.c                 |  5 +++++
 src/lib/process/restrict.h                 |  4 ++--
 src/lib/process/setuid.c                   |  5 +++++
 src/lib/process/setuid.h                   |  5 +++++
 src/lib/process/subprocess.c               |  5 +++++
 src/lib/process/subprocess.h               |  5 +++++
 src/lib/process/waitpid.c                  |  6 ++----
 src/lib/smartlist_core/smartlist_core.h    |  5 +++++
 src/lib/smartlist_core/smartlist_foreach.h |  5 +++++
 src/lib/smartlist_core/smartlist_split.c   |  5 +++++
 src/lib/smartlist_core/smartlist_split.h   |  5 +++++
 src/lib/string/compat_ctype.c              |  5 +++++
 src/lib/string/compat_ctype.h              |  5 +++++
 src/lib/string/compat_string.c             |  6 ++++++
 src/lib/string/compat_string.h             |  5 +++++
 src/lib/string/parse_int.c                 |  5 +++++
 src/lib/string/parse_int.h                 |  5 +++++
 src/lib/string/printf.c                    |  5 +++++
 src/lib/string/printf.h                    |  5 +++++
 src/lib/string/scanf.c                     |  5 +++++
 src/lib/string/scanf.h                     |  5 +++++
 src/lib/string/util_string.c               |  5 +++++
 src/lib/string/util_string.h               |  5 +++++
 src/lib/term/getpass.c                     |  5 +++++
 src/lib/term/getpass.h                     |  5 +++++
 src/lib/testsupport/testsupport.h          | 15 ++++++++++++++-
 src/lib/thread/numcpus.c                   |  5 +++++
 src/lib/thread/numcpus.h                   |  5 +++++
 src/lib/thread/threads.h                   |  5 +++++
 src/lib/time/tvdiff.c                      |  5 +++++
 src/lib/time/tvdiff.h                      |  5 +++++
 src/lib/tls/buffers_tls.c                  |  5 +++++
 src/lib/tls/buffers_tls.h                  |  6 +++++-
 src/lib/trace/debug.h                      |  5 +++++
 src/lib/trace/trace.c                      |  8 +++++++-
 src/lib/trace/trace.h                      |  6 +++++-
 src/lib/wallclock/approx_time.c            |  5 +++++
 src/lib/wallclock/approx_time.h            |  5 +++++
 src/lib/wallclock/timeval.c                |  0
 src/lib/wallclock/timeval.h                |  7 +++++++
 src/lib/wallclock/tm_cvt.c                 |  5 +++++
 src/lib/wallclock/tm_cvt.h                 |  5 +++++
 src/lib/wallclock/tor_gettimeofday.c       |  6 +++---
 src/lib/wallclock/tor_gettimeofday.h       |  5 +++++
 84 files changed, 428 insertions(+), 27 deletions(-)

diff --git a/src/lib/cc/compat_compiler.h b/src/lib/cc/compat_compiler.h
index 0f1acc381..d45316b24 100644
--- a/src/lib/cc/compat_compiler.h
+++ b/src/lib/cc/compat_compiler.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_compiler.h
+ * \brief Utility macros to handle different features and behavior in different
+ *    compilers.
+ **/
+
 #ifndef TOR_COMPAT_COMPILER_H
 #define TOR_COMPAT_COMPILER_H
 
diff --git a/src/lib/cc/torint.h b/src/lib/cc/torint.h
index 91db25833..b97fc8d97 100644
--- a/src/lib/cc/torint.h
+++ b/src/lib/cc/torint.h
@@ -5,18 +5,13 @@
 
 /**
  * \file torint.h
- * \brief Header file to define uint32_t and friends
+ *
+ * \brief Integer definitions used throughout Tor.
  **/
 
 #ifndef TOR_TORINT_H
 #define TOR_TORINT_H
 
-/**
- * \file torint.h
- *
- * \brief Integer definitions used throughout Tor.
- **/
-
 #include "orconfig.h"
 
 #include <stdint.h>
diff --git a/src/lib/crypt_ops/crypto_curve25519.h b/src/lib/crypt_ops/crypto_curve25519.h
index acb36fde3..1bab4a419 100644
--- a/src/lib/crypt_ops/crypto_curve25519.h
+++ b/src/lib/crypt_ops/crypto_curve25519.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2012-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file crypto_curve25519.h
+ * \brief Header for crypto_curve25519.c
+ **/
+
 #ifndef TOR_CRYPTO_CURVE25519_H
 #define TOR_CRYPTO_CURVE25519_H
 
diff --git a/src/lib/crypt_ops/crypto_ed25519.h b/src/lib/crypt_ops/crypto_ed25519.h
index 5ecd4530d..03b3afe20 100644
--- a/src/lib/crypt_ops/crypto_ed25519.h
+++ b/src/lib/crypt_ops/crypto_ed25519.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2012-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file crypto_ed25519.h
+ * \brief Header for crypto_ed25519.c
+ **/
+
 #ifndef TOR_CRYPTO_ED25519_H
 #define TOR_CRYPTO_ED25519_H
 
diff --git a/src/lib/crypt_ops/crypto_format.h b/src/lib/crypt_ops/crypto_format.h
index 4a29b07b3..a24607145 100644
--- a/src/lib/crypt_ops/crypto_format.h
+++ b/src/lib/crypt_ops/crypto_format.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file crypto_format.h
+ * \brief Header for crypto_format.c
+ **/
+
 #ifndef TOR_CRYPTO_FORMAT_H
 #define TOR_CRYPTO_FORMAT_H
 
diff --git a/src/lib/crypt_ops/crypto_openssl_mgt.c b/src/lib/crypt_ops/crypto_openssl_mgt.c
index d1affa725..01de6a9d9 100644
--- a/src/lib/crypt_ops/crypto_openssl_mgt.c
+++ b/src/lib/crypt_ops/crypto_openssl_mgt.c
@@ -5,7 +5,7 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file crypto_openssl.c
+ * \file crypto_openssl_mgt.c
  *
  * \brief Block of functions related to operations from OpenSSL.
  **/
diff --git a/src/lib/crypt_ops/crypto_openssl_mgt.h b/src/lib/crypt_ops/crypto_openssl_mgt.h
index 8251f65ec..a2c53302e 100644
--- a/src/lib/crypt_ops/crypto_openssl_mgt.h
+++ b/src/lib/crypt_ops/crypto_openssl_mgt.h
@@ -5,9 +5,9 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file crypto_openssl.h
+ * \file crypto_openssl_mgt.h
  *
- * \brief Headers for crypto_openssl.c
+ * \brief Headers for crypto_openssl_mgt.c
  **/
 
 #ifndef TOR_CRYPTO_OPENSSL_H
diff --git a/src/lib/defs/dh_sizes.h b/src/lib/defs/dh_sizes.h
index b60957281..a02ffc528 100644
--- a/src/lib/defs/dh_sizes.h
+++ b/src/lib/defs/dh_sizes.h
@@ -4,6 +4,15 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file dh_sizes.h
+
+ * \brief Definitions for sizes of Diffie-Hellman groups elements in Z_p.
+ *
+ * Tor uses these definitions throughout its codebase, even in parts that
+ * don't actually do any Diffie-Hellman calculations.
+ **/
+
 #ifndef TOR_DH_SIZES_H
 #define TOR_DH_SIZES_H
 
diff --git a/src/lib/defs/x25519_sizes.h b/src/lib/defs/x25519_sizes.h
index adaaab8c4..d8ada46b9 100644
--- a/src/lib/defs/x25519_sizes.h
+++ b/src/lib/defs/x25519_sizes.h
@@ -4,6 +4,15 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file x25519_sizes.h
+
+ * \brief Definitions for sizes of x25519 keys and elements.
+ *
+ * Tor uses these definitions throughout its codebase, even in parts that
+ * don't actually do any x25519 calculations.
+ **/
+
 #ifndef TOR_X25519_SIZES_H
 #define TOR_X25519_SIZES_H
 
diff --git a/src/lib/evloop/compat_libevent.h b/src/lib/evloop/compat_libevent.h
index 0a50cfa66..7a5469047 100644
--- a/src/lib/evloop/compat_libevent.h
+++ b/src/lib/evloop/compat_libevent.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2009-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_libevent.h
+ * \brief Header for compat_libevent.c
+ **/
+
 #ifndef TOR_COMPAT_LIBEVENT_H
 #define TOR_COMPAT_LIBEVENT_H
 
diff --git a/src/lib/evloop/timers.h b/src/lib/evloop/timers.h
index 2348c7b7c..4ffed1b45 100644
--- a/src/lib/evloop/timers.h
+++ b/src/lib/evloop/timers.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2016-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file timers.h
+ * \brief Header for timers.c
+ **/
+
 #ifndef TOR_TIMERS_H
 #define TOR_TIMERS_H
 
@@ -28,4 +33,3 @@ STATIC void timers_run_pending(void);
 #endif
 
 #endif /* !defined(TOR_TIMERS_H) */
-
diff --git a/src/lib/evloop/token_bucket.h b/src/lib/evloop/token_bucket.h
index 787317fa1..f004358f4 100644
--- a/src/lib/evloop/token_bucket.h
+++ b/src/lib/evloop/token_bucket.h
@@ -2,8 +2,8 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file token_bucket_rw.h
- * \brief Headers for token_bucket_rw.c
+ * \file token_bucket.h
+ * \brief Headers for token_bucket.c
  **/
 
 #ifndef TOR_TOKEN_BUCKET_H
@@ -115,4 +115,3 @@ STATIC uint32_t rate_per_sec_to_rate_per_step(uint32_t rate);
 #endif
 
 #endif /* TOR_TOKEN_BUCKET_H */
-
diff --git a/src/lib/evloop/workqueue.h b/src/lib/evloop/workqueue.h
index 4e5c424be..da292d1f0 100644
--- a/src/lib/evloop/workqueue.h
+++ b/src/lib/evloop/workqueue.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2013-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file workqueue.h
+ * \brief Header for workqueue.c
+ **/
+
 #ifndef TOR_WORKQUEUE_H
 #define TOR_WORKQUEUE_H
 
diff --git a/src/lib/log/escape.c b/src/lib/log/escape.c
index 756171030..b6b20183b 100644
--- a/src/lib/log/escape.c
+++ b/src/lib/log/escape.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file escape.c
+ * \brief Escape untrusted strings before sending them to the log.
+ **/
+
 #include "lib/log/escape.h"
 #include "lib/log/util_bug.h"
 #include "lib/string/compat_ctype.h"
diff --git a/src/lib/log/escape.h b/src/lib/log/escape.h
index 5d2e79d6c..f47e7e004 100644
--- a/src/lib/log/escape.h
+++ b/src/lib/log/escape.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file escape.h
+ * \brief Header for escape.c
+ **/
+
 #ifndef TOR_ESCAPE_H
 #define TOR_ESCAPE_H
 
diff --git a/src/lib/log/ratelim.c b/src/lib/log/ratelim.c
index 677c49911..fba702d7f 100644
--- a/src/lib/log/ratelim.c
+++ b/src/lib/log/ratelim.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ratelim.c
+ * \brief Summarize similar messages that would otherwise flood the logs.
+ **/
+
 #include "lib/log/ratelim.h"
 #include "lib/malloc/util_malloc.h"
 #include "lib/string/printf.h"
diff --git a/src/lib/log/ratelim.h b/src/lib/log/ratelim.h
index 4ee6c5fed..d423e10b8 100644
--- a/src/lib/log/ratelim.h
+++ b/src/lib/log/ratelim.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ratelim.h
+ * \brief Summarize similar messages that would otherwise flood the logs.
+ **/
+
 #ifndef TOR_RATELIM_H
 #define TOR_RATELIM_H
 
diff --git a/src/lib/log/win32err.c b/src/lib/log/win32err.c
index 4586c23c8..6603ed464 100644
--- a/src/lib/log/win32err.c
+++ b/src/lib/log/win32err.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file win32err.c
+ * \brief Convert windows error codes to useful C strings.
+ **/
+
 #ifdef _WIN32
 #include "orconfig.h"
 #include "lib/log/win32err.h"
diff --git a/src/lib/log/win32err.h b/src/lib/log/win32err.h
index 61d3af57d..92958c987 100644
--- a/src/lib/log/win32err.h
+++ b/src/lib/log/win32err.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file win32err.h
+ * \brief Header for win32err.c
+ **/
+
 #ifndef TOR_WIN32ERR_H
 #define TOR_WIN32ERR_H
 
diff --git a/src/lib/net/buffers_net.c b/src/lib/net/buffers_net.c
index edc9954f2..2e6a096a0 100644
--- a/src/lib/net/buffers_net.c
+++ b/src/lib/net/buffers_net.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file buffers_net.c
+ * \brief Read and write data on a buf_t object.
+ **/
+
 #define BUFFERS_PRIVATE
 #include "lib/net/buffers_net.h"
 #include "lib/container/buffers.h"
diff --git a/src/lib/net/gethostname.c b/src/lib/net/gethostname.c
index b6cc9b8e5..1c4431af2 100644
--- a/src/lib/net/gethostname.c
+++ b/src/lib/net/gethostname.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file gethostname.c
+ * \brief Mockable wrapper for gethostname().
+ */
+
 #include "orconfig.h"
 #include "lib/net/gethostname.h"
 
diff --git a/src/lib/net/gethostname.h b/src/lib/net/gethostname.h
index d83c5fe09..7bf0ce592 100644
--- a/src/lib/net/gethostname.h
+++ b/src/lib/net/gethostname.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file gethostname.h
+ * \brief Header for gethostname.c
+ **/
+
 #ifndef TOR_GETHOSTNAME_H
 #define TOR_GETHOSTNAME_H
 
diff --git a/src/lib/net/ipv4.c b/src/lib/net/ipv4.c
index 18e69761e..db1429f49 100644
--- a/src/lib/net/ipv4.c
+++ b/src/lib/net/ipv4.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ipv4.c
+ * \brief Functions for encoding and decoding IPv4 addresses into strings
+ **/
+
 #include "orconfig.h"
 #include "lib/cc/torint.h"
 #include "lib/net/ipv4.h"
diff --git a/src/lib/net/ipv4.h b/src/lib/net/ipv4.h
index 1ccc72997..0127f09e0 100644
--- a/src/lib/net/ipv4.h
+++ b/src/lib/net/ipv4.h
@@ -3,6 +3,10 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ipv4.h
+ * \brief Header for ipv4.c
+ **/
 #ifndef TOR_IPV4_H
 #define TOR_IPV4_H
 
diff --git a/src/lib/net/ipv6.c b/src/lib/net/ipv6.c
index 35d7ddb90..630d6f1db 100644
--- a/src/lib/net/ipv6.c
+++ b/src/lib/net/ipv6.c
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ipv6.c
+ * \brief Functions for encoding and decoding IPv6 addresses
+ *
+ * (Because these functions are generic, they can also handle IPv4 addresses).
+ **/
+
 #include "lib/net/ipv6.h"
 #include "lib/net/ipv4.h"
 #include "lib/string/util_string.h"
diff --git a/src/lib/net/ipv6.h b/src/lib/net/ipv6.h
index 0a12e046a..4e5ef4da8 100644
--- a/src/lib/net/ipv6.h
+++ b/src/lib/net/ipv6.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file ipv6.h
+ * \brief Header for ipv6.c
+ **/
+
 #ifndef TOR_IPV6_H
 #define TOR_IPV6_H
 
diff --git a/src/lib/net/nettypes.h b/src/lib/net/nettypes.h
index f21237436..f7f2ec7d6 100644
--- a/src/lib/net/nettypes.h
+++ b/src/lib/net/nettypes.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file nettypes.h
+ * \brief Declarations for types used throughout the Tor networking system
+ **/
+
 #ifndef TOR_NET_TYPES_H
 #define TOR_NET_TYPES_H
 
diff --git a/src/lib/net/resolve.c b/src/lib/net/resolve.c
index cbe368ccf..c620d4f6a 100644
--- a/src/lib/net/resolve.c
+++ b/src/lib/net/resolve.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file resolve.c
+ * \brief Use the libc DNS resolver to convert hostnames into addresses.
+ **/
+
 #include "lib/net/resolve.h"
 #include "lib/net/address.h"
 #include "lib/malloc/util_malloc.h"
diff --git a/src/lib/net/resolve.h b/src/lib/net/resolve.h
index f2280ae7e..c91aecfee 100644
--- a/src/lib/net/resolve.h
+++ b/src/lib/net/resolve.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file resolve.h
+ * \brief Header for resolve.c
+ **/
+
 #ifndef TOR_RESOLVE_H
 #define TOR_RESOLVE_H
 
diff --git a/src/lib/net/socket.c b/src/lib/net/socket.c
index dc3d1531f..1b3238d99 100644
--- a/src/lib/net/socket.c
+++ b/src/lib/net/socket.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file socket.c
+ * \brief Compatibility and utility functions for working with network
+ *    sockets.
+ **/
+
 #define SOCKET_PRIVATE
 #include "lib/net/socket.h"
 #include "lib/net/address.h"
diff --git a/src/lib/net/socket.h b/src/lib/net/socket.h
index cb0ccbe81..e2092c727 100644
--- a/src/lib/net/socket.h
+++ b/src/lib/net/socket.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file socket.h
+ * \brief Header for socket.c
+ **/
+
 #ifndef TOR_SOCKET_H
 #define TOR_SOCKET_H
 
diff --git a/src/lib/net/socks5_status.h b/src/lib/net/socks5_status.h
index 74b9c9102..0f3113254 100644
--- a/src/lib/net/socks5_status.h
+++ b/src/lib/net/socks5_status.h
@@ -3,6 +3,16 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file socks5_status.h
+ * \brief Status codes used by the SOCKS5 protocol.
+ **/
+
+/* NOTE: it probably isn't necessary to put this header in lib/net, but
+ * we need it in _some_ lower-level layer for now, since it is used by
+ * tools/tor-resolve.c.
+ */
+
 #ifndef TOR_SOCKS5_STATUS_H
 #define TOR_SOCKS5_STATUS_H
 
diff --git a/src/lib/osinfo/uname.c b/src/lib/osinfo/uname.c
index a0fa26d1d..9d1923695 100644
--- a/src/lib/osinfo/uname.c
+++ b/src/lib/osinfo/uname.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file uname.c
+ * \brief Look up a description of the operating system.
+ **/
+
 #include "orconfig.h"
 #include "lib/osinfo/uname.h"
 
diff --git a/src/lib/osinfo/uname.h b/src/lib/osinfo/uname.h
index 1f0b78385..ef8cd078e 100644
--- a/src/lib/osinfo/uname.h
+++ b/src/lib/osinfo/uname.h
@@ -1,3 +1,12 @@
+/* Copyright (c) 2003-2004, Roger Dingledine
+ * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
+ * Copyright (c) 2007-2018, The Tor Project, Inc. */
+/* See LICENSE for licensing information */
+
+/**
+ * \file uname.h
+ * \brief Header for uname.c
+ **/
 
 #ifndef HAVE_TOR_UNAME_H
 #define HAVE_TOR_UNAME_H
diff --git a/src/lib/process/daemon.c b/src/lib/process/daemon.c
index edffb0468..6863d05d7 100644
--- a/src/lib/process/daemon.c
+++ b/src/lib/process/daemon.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file daemon.c
+ * \brief Run the tor process in the background (unix only)
+ **/
+
 #include "orconfig.h"
 #include "lib/process/daemon.h"
 
diff --git a/src/lib/process/daemon.h b/src/lib/process/daemon.h
index 48a65b22e..1f26e9222 100644
--- a/src/lib/process/daemon.h
+++ b/src/lib/process/daemon.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file daemon.h
+ * \brief Header for daemon.c
+ **/
+
 #ifndef TOR_DAEMON_H
 #define TOR_DAEMON_H
 
diff --git a/src/lib/process/env.c b/src/lib/process/env.c
index 731f609ac..244cd4a4e 100644
--- a/src/lib/process/env.c
+++ b/src/lib/process/env.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file env.c
+ * \brief Inspect and manipulate the environment variables.
+ **/
+
 #include "orconfig.h"
 #include "lib/process/env.h"
 
diff --git a/src/lib/process/env.h b/src/lib/process/env.h
index f22599355..288b923ac 100644
--- a/src/lib/process/env.h
+++ b/src/lib/process/env.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file env.h
+ * \brief Header for env.c
+ **/
+
 #ifndef TOR_ENV_H
 #define TOR_ENV_H
 
diff --git a/src/lib/process/pidfile.c b/src/lib/process/pidfile.c
index f016f2169..17ff8be60 100644
--- a/src/lib/process/pidfile.c
+++ b/src/lib/process/pidfile.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file pidfile.c
+ * \brief Record this process's PID to disk.
+ **/
+
 #include "orconfig.h"
 #include "lib/process/pidfile.h"
 
diff --git a/src/lib/process/pidfile.h b/src/lib/process/pidfile.h
index c85cd1905..945edee99 100644
--- a/src/lib/process/pidfile.h
+++ b/src/lib/process/pidfile.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file pidfile.h
+ * \brief Header for pidfile.c
+ **/
+
 #ifndef TOR_PIDFILE_H
 #define TOR_PIDFILE_H
 
diff --git a/src/lib/process/restrict.c b/src/lib/process/restrict.c
index bb44cc3d1..fc1a30880 100644
--- a/src/lib/process/restrict.c
+++ b/src/lib/process/restrict.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file restrict.c
+ * \brief Drop privileges from the current process.
+ **/
+
 #include "orconfig.h"
 #include "lib/process/restrict.h"
 #include "lib/intmath/cmp.h"
diff --git a/src/lib/process/restrict.h b/src/lib/process/restrict.h
index c7f76f823..2e78dc468 100644
--- a/src/lib/process/restrict.h
+++ b/src/lib/process/restrict.h
@@ -4,8 +4,8 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file waitpid.h
- * \brief Headers for waitpid.c
+ * \file restrict.h
+ * \brief Header for restrict.c
  **/
 
 #ifndef TOR_RESTRICT_H
diff --git a/src/lib/process/setuid.c b/src/lib/process/setuid.c
index fa1cdc0f3..5423259a6 100644
--- a/src/lib/process/setuid.c
+++ b/src/lib/process/setuid.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file setuid.c
+ * \brief Change the user ID after Tor has started (Unix only)
+ **/
+
 #include "orconfig.h"
 #include "lib/process/setuid.h"
 
diff --git a/src/lib/process/setuid.h b/src/lib/process/setuid.h
index 61aeefe1b..49751c97c 100644
--- a/src/lib/process/setuid.h
+++ b/src/lib/process/setuid.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file setuid.h
+ * \brief Header for setuid.c
+ **/
+
 #ifndef TOR_SETUID_H
 #define TOR_SETUID_H
 
diff --git a/src/lib/process/subprocess.c b/src/lib/process/subprocess.c
index 516494d10..9a12f5e76 100644
--- a/src/lib/process/subprocess.c
+++ b/src/lib/process/subprocess.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file subprocess.c
+ * \brief Launch and monitor other processes.
+ **/
+
 #define SUBPROCESS_PRIVATE
 #include "lib/process/subprocess.h"
 
diff --git a/src/lib/process/subprocess.h b/src/lib/process/subprocess.h
index a319b3505..5b4318ef2 100644
--- a/src/lib/process/subprocess.h
+++ b/src/lib/process/subprocess.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file subprocess.h
+ * \brief Header for subprocess.c
+ **/
+
 #ifndef TOR_SUBPROCESS_H
 #define TOR_SUBPROCESS_H
 
diff --git a/src/lib/process/waitpid.c b/src/lib/process/waitpid.c
index 66c77b05f..27f69b08f 100644
--- a/src/lib/process/waitpid.c
+++ b/src/lib/process/waitpid.c
@@ -4,10 +4,8 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file util_process.c
- * \brief utility functions for launching processes and checking their
- *    status. These functions are kept separately from procmon so that they
- *    won't require linking against libevent.
+ * \file waitpid.c
+ * \brief Convenience structures for handlers for handling waitpid().
  **/
 
 #include "orconfig.h"
diff --git a/src/lib/smartlist_core/smartlist_core.h b/src/lib/smartlist_core/smartlist_core.h
index b1adf2ebd..974fb0175 100644
--- a/src/lib/smartlist_core/smartlist_core.h
+++ b/src/lib/smartlist_core/smartlist_core.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file smartlist_core.h
+ * \brief Top-level declarations for the smartlist_t dynamic array type.
+ **/
+
 #ifndef TOR_SMARTLIST_CORE_H
 #define TOR_SMARTLIST_CORE_H
 
diff --git a/src/lib/smartlist_core/smartlist_foreach.h b/src/lib/smartlist_core/smartlist_foreach.h
index 4bef36d99..54f08ac47 100644
--- a/src/lib/smartlist_core/smartlist_foreach.h
+++ b/src/lib/smartlist_core/smartlist_foreach.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file smartlist_foreach.h
+ * \brief Macros for iterating over the elements of a smartlist_t.
+ **/
+
 #ifndef TOR_SMARTLIST_FOREACH_H
 #define TOR_SMARTLIST_FOREACH_H
 
diff --git a/src/lib/smartlist_core/smartlist_split.c b/src/lib/smartlist_core/smartlist_split.c
index b9340e792..9c8368f66 100644
--- a/src/lib/smartlist_core/smartlist_split.c
+++ b/src/lib/smartlist_core/smartlist_split.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file smartlist_split.c
+ * \brief Split a string into a smartlist_t of substrings.
+ **/
+
 #include "lib/smartlist_core/smartlist_core.h"
 #include "lib/smartlist_core/smartlist_split.h"
 
diff --git a/src/lib/smartlist_core/smartlist_split.h b/src/lib/smartlist_core/smartlist_split.h
index 8ed2abafb..4dd48295c 100644
--- a/src/lib/smartlist_core/smartlist_split.h
+++ b/src/lib/smartlist_core/smartlist_split.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file smartlist_split.h
+ * \brief Header for smartlist_split.c
+ **/
+
 #ifndef TOR_SMARTLIST_SPLIT_H
 #define TOR_SMARTLIST_SPLIT_H
 
diff --git a/src/lib/string/compat_ctype.c b/src/lib/string/compat_ctype.c
index d1d4ce0ff..35f4ec653 100644
--- a/src/lib/string/compat_ctype.c
+++ b/src/lib/string/compat_ctype.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_ctype.c
+ * \brief Locale-independent character-type inspection (backend)
+ **/
+
 #include "lib/string/compat_ctype.h"
 
 /**
diff --git a/src/lib/string/compat_ctype.h b/src/lib/string/compat_ctype.h
index 530a10270..210c460c3 100644
--- a/src/lib/string/compat_ctype.h
+++ b/src/lib/string/compat_ctype.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_ctype.h
+ * \brief Locale-independent character-type inspection (header)
+ **/
+
 #ifndef TOR_COMPAT_CTYPE_H
 #define TOR_COMPAT_CTYPE_H
 
diff --git a/src/lib/string/compat_string.c b/src/lib/string/compat_string.c
index 8b063b724..eae82fdae 100644
--- a/src/lib/string/compat_string.c
+++ b/src/lib/string/compat_string.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_string.c
+ * \brief Useful string-processing functions that some platforms don't
+ * provide.
+ **/
+
 #include "lib/string/compat_string.h"
 #include "lib/err/torerr.h"
 
diff --git a/src/lib/string/compat_string.h b/src/lib/string/compat_string.h
index 4726d2b5b..929271733 100644
--- a/src/lib/string/compat_string.h
+++ b/src/lib/string/compat_string.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_string.h
+ * \brief Header for compat_string.c
+ **/
+
 #ifndef TOR_COMPAT_STRING_H
 #define TOR_COMPAT_STRING_H
 
diff --git a/src/lib/string/parse_int.c b/src/lib/string/parse_int.c
index e552730cc..52ff49ef1 100644
--- a/src/lib/string/parse_int.c
+++ b/src/lib/string/parse_int.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file parse_int.c
+ * \brief Convert strings into the integers they encode, with bounds checking.
+ **/
+
 #include "lib/string/parse_int.h"
 
 #include <errno.h>
diff --git a/src/lib/string/parse_int.h b/src/lib/string/parse_int.h
index 6f56fc32a..663a5acd7 100644
--- a/src/lib/string/parse_int.h
+++ b/src/lib/string/parse_int.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file parse_int.h
+ * \brief Header for parse_int.c
+ **/
+
 #ifndef TOR_PARSE_INT_H
 #define TOR_PARSE_INT_H
 
diff --git a/src/lib/string/printf.c b/src/lib/string/printf.c
index 4443e25fb..f8be3b470 100644
--- a/src/lib/string/printf.c
+++ b/src/lib/string/printf.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file printf.c
+ * \brief Compatibility wrappers around snprintf and its friends
+ **/
+
 #include "lib/string/printf.h"
 #include "lib/err/torerr.h"
 #include "lib/cc/torint.h"
diff --git a/src/lib/string/printf.h b/src/lib/string/printf.h
index 69b724379..49c37d43e 100644
--- a/src/lib/string/printf.h
+++ b/src/lib/string/printf.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file printf.h
+ * \brief Header for printf.c
+ **/
+
 #ifndef TOR_UTIL_PRINTF_H
 #define TOR_UTIL_PRINTF_H
 
diff --git a/src/lib/string/scanf.c b/src/lib/string/scanf.c
index 0c5082799..7b0844214 100644
--- a/src/lib/string/scanf.c
+++ b/src/lib/string/scanf.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file scanf.c
+ * \brief Locale-independent minimal implementation of sscanf().
+ **/
+
 #include "lib/string/scanf.h"
 #include "lib/string/compat_ctype.h"
 #include "lib/cc/torint.h"
diff --git a/src/lib/string/scanf.h b/src/lib/string/scanf.h
index 9cfa9cc6c..ada2322bb 100644
--- a/src/lib/string/scanf.h
+++ b/src/lib/string/scanf.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file scanf.h
+ * \brief Header for scanf.c
+ **/
+
 #ifndef TOR_UTIL_SCANF_H
 #define TOR_UTIL_SCANF_H
 
diff --git a/src/lib/string/util_string.c b/src/lib/string/util_string.c
index e8ed3d4f5..a6b0a3d68 100644
--- a/src/lib/string/util_string.c
+++ b/src/lib/string/util_string.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file util_string.c
+ * \brief Non-standard string functions used throughout Tor.
+ **/
+
 #include "lib/string/util_string.h"
 #include "lib/string/compat_ctype.h"
 #include "lib/err/torerr.h"
diff --git a/src/lib/string/util_string.h b/src/lib/string/util_string.h
index 75407d5ff..471613462 100644
--- a/src/lib/string/util_string.h
+++ b/src/lib/string/util_string.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file util_string.h
+ * \brief Header for util_string.c
+ **/
+
 #ifndef TOR_UTIL_STRING_H
 #define TOR_UTIL_STRING_H
 
diff --git a/src/lib/term/getpass.c b/src/lib/term/getpass.c
index 10c99914f..590411b71 100644
--- a/src/lib/term/getpass.c
+++ b/src/lib/term/getpass.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file getpass.c
+ * \brief Cross-platform wrapper to read passphrases from the terminal.
+ **/
+
 #include "lib/term/getpass.h"
 
 #include "lib/log/util_bug.h"
diff --git a/src/lib/term/getpass.h b/src/lib/term/getpass.h
index 9d03f7036..e8347e7fe 100644
--- a/src/lib/term/getpass.h
+++ b/src/lib/term/getpass.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file getpass.h
+ * \brief Header for getpass.c
+ **/
+
 #ifndef TOR_GETPASS_H
 #define TOR_GETPASS_H
 
diff --git a/src/lib/testsupport/testsupport.h b/src/lib/testsupport/testsupport.h
index 9a55d306f..3ae1b48f8 100644
--- a/src/lib/testsupport/testsupport.h
+++ b/src/lib/testsupport/testsupport.h
@@ -1,10 +1,24 @@
 /* Copyright (c) 2013-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file testsupport.h
+ *
+ * \brief Macros to implement mocking and selective exposure for the test code.
+ *
+ * Each Tor source file is built twice: once with TOR_UNIT_TESTS defined, and
+ * once with it undefined.  The only difference between these configurations
+ * should be that when building for the tests, more functions are exposed as
+ * non-static, and a number of functions are declared as mockable.
+ **/
+
 #ifndef TOR_TESTSUPPORT_H
 #define TOR_TESTSUPPORT_H
 
 #ifdef TOR_UNIT_TESTS
+/** The "STATIC" macro marks a function or variable that is static when
+ * building Tor for production, but non-static when building the unit
+ * tests. */
 #define STATIC
 #define EXTERN(type, name) extern type name;
 #else
@@ -87,4 +101,3 @@
 /** @} */
 
 #endif /* !defined(TOR_TESTSUPPORT_H) */
-
diff --git a/src/lib/thread/numcpus.c b/src/lib/thread/numcpus.c
index 534b0570f..b8763f118 100644
--- a/src/lib/thread/numcpus.c
+++ b/src/lib/thread/numcpus.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file numcpus.c
+ * \brief Compute the number of CPUs configured on this system.
+ **/
+
 #include "orconfig.h"
 #include "lib/thread/numcpus.h"
 #include "lib/log/torlog.h"
diff --git a/src/lib/thread/numcpus.h b/src/lib/thread/numcpus.h
index 2899a9ec8..0b026e424 100644
--- a/src/lib/thread/numcpus.h
+++ b/src/lib/thread/numcpus.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file numcpus.h
+ * \brief Header for numcpus.c
+ **/
+
 #ifndef TOR_NUMCPUS_H
 #define TOR_NUMCPUS_H
 
diff --git a/src/lib/thread/threads.h b/src/lib/thread/threads.h
index fcccc643d..89d2a9d93 100644
--- a/src/lib/thread/threads.h
+++ b/src/lib/thread/threads.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file threads.h
+ * \brief Header for threads.c
+ **/
+
 #ifndef TOR_COMPAT_THREADS_H
 #define TOR_COMPAT_THREADS_H
 
diff --git a/src/lib/time/tvdiff.c b/src/lib/time/tvdiff.c
index cfd1ace77..6af12501c 100644
--- a/src/lib/time/tvdiff.c
+++ b/src/lib/time/tvdiff.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file tvdiff.c
+ * \brief Compute the difference between timevals, in various units.
+ **/
+
 #include "lib/time/tvdiff.h"
 
 #include "lib/cc/compat_compiler.h"
diff --git a/src/lib/time/tvdiff.h b/src/lib/time/tvdiff.h
index 215de9cf3..d78330d7d 100644
--- a/src/lib/time/tvdiff.h
+++ b/src/lib/time/tvdiff.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file tvdiff.h
+ * \brief Header for tvdiff.c
+ **/
+
 #ifndef TOR_TVDIFF_H
 #define TOR_TVDIFF_H
 
diff --git a/src/lib/tls/buffers_tls.c b/src/lib/tls/buffers_tls.c
index 243e0eb0b..0e112b59c 100644
--- a/src/lib/tls/buffers_tls.c
+++ b/src/lib/tls/buffers_tls.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file buffers_tls.c
+ * \brief Read and write data on a tor_tls_t connection from a buf_t object.
+ **/
+
 #define BUFFERS_PRIVATE
 #include "orconfig.h"
 #include <stddef.h>
diff --git a/src/lib/tls/buffers_tls.h b/src/lib/tls/buffers_tls.h
index d9d26c82b..7a1ca6d16 100644
--- a/src/lib/tls/buffers_tls.h
+++ b/src/lib/tls/buffers_tls.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file buffers_tls.h
+ * \brief Header for buffers_tls.c
+ **/
+
 #ifndef TOR_BUFFERS_TLS_H
 #define TOR_BUFFERS_TLS_H
 
@@ -16,4 +21,3 @@ int buf_flush_to_tls(struct buf_t *buf, struct tor_tls_t *tls,
                      size_t sz, size_t *buf_flushlen);
 
 #endif /* !defined(TOR_BUFFERS_TLS_H) */
-
diff --git a/src/lib/trace/debug.h b/src/lib/trace/debug.h
index 9b5d9d05c..a764f552e 100644
--- a/src/lib/trace/debug.h
+++ b/src/lib/trace/debug.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file debug.h
+ * \brief Macros for debugging our event-trace support.
+ **/
+
 #ifndef TOR_TRACE_LOG_DEBUG_H
 #define TOR_TRACE_LOG_DEBUG_H
 
diff --git a/src/lib/trace/trace.c b/src/lib/trace/trace.c
index c0bbbb0cc..535ffde18 100644
--- a/src/lib/trace/trace.c
+++ b/src/lib/trace/trace.c
@@ -1,6 +1,13 @@
 /* Copyright (c) 2017-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file trace.c
+ * \brief Common functions for event-tracing implementation
+ *
+ * See trace.h and doc/HACKING/Tracing.md for more information.
+ **/
+
 #include "lib/trace/trace.h"
 
 /** Initialize the tracing library. */
@@ -8,4 +15,3 @@ void
 tor_trace_init(void)
 {
 }
-
diff --git a/src/lib/trace/trace.h b/src/lib/trace/trace.h
index 2dd51aace..5f7b0ee7c 100644
--- a/src/lib/trace/trace.h
+++ b/src/lib/trace/trace.h
@@ -1,10 +1,14 @@
 /* Copyright (c) 2017-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file trace.h
+ * \brief Header for trace.c
+ **/
+
 #ifndef TOR_TRACE_TRACE_H
 #define TOR_TRACE_TRACE_H
 
 void tor_trace_init(void);
 
 #endif // TOR_TRACE_TRACE_H
-
diff --git a/src/lib/wallclock/approx_time.c b/src/lib/wallclock/approx_time.c
index 2528954f1..bb9a29236 100644
--- a/src/lib/wallclock/approx_time.c
+++ b/src/lib/wallclock/approx_time.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file approx_time.c
+ * \brief Cache the last result of time(), for performance and testing.
+ **/
+
 #include "orconfig.h"
 #include "lib/wallclock/approx_time.h"
 
diff --git a/src/lib/wallclock/approx_time.h b/src/lib/wallclock/approx_time.h
index c57ff5bcd..becc632fe 100644
--- a/src/lib/wallclock/approx_time.h
+++ b/src/lib/wallclock/approx_time.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file approx_time.h
+ * \brief Header for approx_time.c
+ **/
+
 #ifndef TOR_APPROX_TIME_H
 #define TOR_APPROX_TIME_H
 
diff --git a/src/lib/wallclock/timeval.c b/src/lib/wallclock/timeval.c
deleted file mode 100644
index e69de29bb..000000000
diff --git a/src/lib/wallclock/timeval.h b/src/lib/wallclock/timeval.h
index 6a9b36a02..b34277cda 100644
--- a/src/lib/wallclock/timeval.h
+++ b/src/lib/wallclock/timeval.h
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file timeval.h
+ *
+ * \brief Declarations for timeval-related macros that some platforms
+ * are missing.
+ **/
+
 #ifndef TOR_TIMEVAL_H
 #define TOR_TIMEVAL_H
 
diff --git a/src/lib/wallclock/tm_cvt.c b/src/lib/wallclock/tm_cvt.c
index 31d929e63..4a51a4ab3 100644
--- a/src/lib/wallclock/tm_cvt.c
+++ b/src/lib/wallclock/tm_cvt.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file tm_cvt.c
+ * \brief Convert to and from struct tm, portably.
+ **/
+
 #include "orconfig.h"
 #include "lib/cc/torint.h"
 #include "lib/cc/compat_compiler.h"
diff --git a/src/lib/wallclock/tm_cvt.h b/src/lib/wallclock/tm_cvt.h
index 4d87acd4f..a1cdc80ef 100644
--- a/src/lib/wallclock/tm_cvt.h
+++ b/src/lib/wallclock/tm_cvt.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file tm_cvt.h
+ * \brief Header for tm_cvt.c
+ **/
+
 #ifndef TOR_WALLCLOCK_TM_CVT_H
 #define TOR_WALLCLOCK_TM_CVT_H
 
diff --git a/src/lib/wallclock/tor_gettimeofday.c b/src/lib/wallclock/tor_gettimeofday.c
index eb902e681..aefe796ad 100644
--- a/src/lib/wallclock/tor_gettimeofday.c
+++ b/src/lib/wallclock/tor_gettimeofday.c
@@ -4,9 +4,9 @@
 /* See LICENSE for licensing information */
 
 /**
- * \file compat_time.c
- * \brief Portable wrappers for finding out the current time, running
- *   timers, etc.
+ * \file tor_gettimeofday.c
+ * \brief Implementat gettimeofday() for windows, and other platforms without
+ *   it.
  **/
 
 #include "orconfig.h"
diff --git a/src/lib/wallclock/tor_gettimeofday.h b/src/lib/wallclock/tor_gettimeofday.h
index 728ad9565..aac6366a6 100644
--- a/src/lib/wallclock/tor_gettimeofday.h
+++ b/src/lib/wallclock/tor_gettimeofday.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file tor_gettimeofday.h
+ * \brief Header for tor_gettimeofday.c
+ **/
+
 #ifndef TOR_GETTIMEOFDAY_H
 #define TOR_GETTIMEOFDAY_H
 

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits