Merge branch 'tor-github/pr/1476'

130 files changed, 666 insertions, 46 deletions

diff --git a/changes/ticket32307 b/changes/ticket32307
new file mode 100644
index 0000000000..1e68430991
--- /dev/null
+++ b/changes/ticket32307
@@ -0,0 +1,4 @@
+  o Minor features (documentation):
+    - Make sure that doxygen outputs documentation for all of our C files.
+      Previously, some were missing @file declarations, causing them to be
+      ignored. Closes ticket 32307.
diff --git a/src/app/config/quiet_level.c b/src/app/config/quiet_level.c
index f00d6b5a3b..84bc0149b8 100644
--- a/src/app/config/quiet_level.c
+++ b/src/app/config/quiet_level.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file quiet_level.c
+ * @brief Code to handle default logging level (quiet/hush/normal).
+ **/
+
 #include "orconfig.h"
 #include "lib/log/log.h"
 #include "app/config/quiet_level.h"
diff --git a/src/app/main/subsysmgr.c b/src/app/main/subsysmgr.c
index 5aa4fd76c9..1f4bc840f2 100644
--- a/src/app/main/subsysmgr.c
+++ b/src/app/main/subsysmgr.c
@@ -3,6 +3,14 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file subsysmgr.c
+ * @brief Manager for Tor's subsystems.
+ *
+ * This code is responsible for initializing, configuring, and shutting
+ * down all of Tor's individual subsystems.
+ **/
+
 #include "orconfig.h"
 #include "app/main/subsysmgr.h"
 
diff --git a/src/app/main/subsysmgr.h b/src/app/main/subsysmgr.h
index d4426614e3..f8bc83e0ad 100644
--- a/src/app/main/subsysmgr.h
+++ b/src/app/main/subsysmgr.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file subsysmgr.h
+ * @brief Header for subsysmgr.c
+ **/
+
 #ifndef TOR_SUBSYSMGR_T
 #define TOR_SUBSYSMGR_T
 
diff --git a/src/app/main/subsystem_list.c b/src/app/main/subsystem_list.c
index 1af9340c1a..4a40702e70 100644
--- a/src/app/main/subsystem_list.c
+++ b/src/app/main/subsystem_list.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file subsystem_list.c
+ * @brief List of Tor's subsystems.
+ **/
+
 #include "orconfig.h"
 #include "app/main/subsysmgr.h"
 #include "lib/cc/compat_compiler.h"
diff --git a/src/core/crypto/hs_ntor.h b/src/core/crypto/hs_ntor.h
index e5a5171915..5a70974a0c 100644
--- a/src/core/crypto/hs_ntor.h
+++ b/src/core/crypto/hs_ntor.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file hs_ntor.h
+ * @brief Header for hs_ntor.c
+ **/
+
 #ifndef TOR_HS_NTOR_H
 #define TOR_HS_NTOR_H
 
diff --git a/src/core/crypto/onion_ntor.h b/src/core/crypto/onion_ntor.h
index 51e72b4083..ea504c1050 100644
--- a/src/core/crypto/onion_ntor.h
+++ b/src/core/crypto/onion_ntor.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2012-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file onion_ntor.h
+ * @brief Header for onion_ntor.c
+ **/
+
 #ifndef TOR_ONION_NTOR_H
 #define TOR_ONION_NTOR_H
 
diff --git a/src/core/crypto/relay_crypto.c b/src/core/crypto/relay_crypto.c
index 8a285131a8..3213e6a476 100644
--- a/src/core/crypto/relay_crypto.c
+++ b/src/core/crypto/relay_crypto.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file relay_crypto.h
+ * @brief Header for relay_crypto.c
+ **/
+
 #include "core/or/or.h"
 #include "core/or/circuitlist.h"
 #include "core/or/crypt_path.h"
diff --git a/src/core/mainloop/mainloop_pubsub.c b/src/core/mainloop/mainloop_pubsub.c
index 53275d8119..764a1b0cc9 100644
--- a/src/core/mainloop/mainloop_pubsub.c
+++ b/src/core/mainloop/mainloop_pubsub.c
@@ -4,6 +4,15 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file mainloop_pubsub.c
+ * @brief Connect the publish-subscribe code to the main-loop.
+ *
+ * This module is responsible for instantiating all the channels used by the
+ * publish-subscribe code, and making sure that each one's messages are
+ * processed when appropriate.
+ **/
+
 #include "orconfig.h"
 
 #include "core/or/or.h"
diff --git a/src/core/mainloop/mainloop_pubsub.h b/src/core/mainloop/mainloop_pubsub.h
index 365a3dd565..bd57c0c174 100644
--- a/src/core/mainloop/mainloop_pubsub.h
+++ b/src/core/mainloop/mainloop_pubsub.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file mainloop_pubsub.h
+ * @brief Header for mainloop_pubsub.c
+ **/
+
 #ifndef TOR_MAINLOOP_PUBSUB_H
 #define TOR_MAINLOOP_PUBSUB_H
 
diff --git a/src/core/mainloop/mainloop_sys.c b/src/core/mainloop/mainloop_sys.c
index fbd5a40327..f14ecb261b 100644
--- a/src/core/mainloop/mainloop_sys.c
+++ b/src/core/mainloop/mainloop_sys.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file mainloop_sys.c
+ * @brief Declare the "mainloop" subsystem.
+ **/
+
 #include "core/or/or.h"
 #include "core/mainloop/mainloop_sys.h"
 #include "core/mainloop/mainloop.h"
diff --git a/src/core/mainloop/mainloop_sys.h b/src/core/mainloop/mainloop_sys.h
index fa74fe5d4b..434a25a44b 100644
--- a/src/core/mainloop/mainloop_sys.h
+++ b/src/core/mainloop/mainloop_sys.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file mainloop_sys.h
+ * @brief Header for mainloop_sys.c
+ **/
+
 #ifndef MAINLOOP_SYS_H
 #define MAINLOOP_SYS_H
 
diff --git a/src/core/mainloop/netstatus.c b/src/core/mainloop/netstatus.c
index 4924888598..c34e613d1f 100644
--- a/src/core/mainloop/netstatus.c
+++ b/src/core/mainloop/netstatus.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file netstatus.c
+ * @brief Track whether the network is disabled, dormant, etc.
+ **/
+
 #include "core/or/or.h"
 #include "core/mainloop/netstatus.h"
 #include "core/mainloop/mainloop.h"
diff --git a/src/core/mainloop/netstatus.h b/src/core/mainloop/netstatus.h
index e8469ff558..ce3d2e23f9 100644
--- a/src/core/mainloop/netstatus.h
+++ b/src/core/mainloop/netstatus.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file netstatus.h
+ * @brief Header for netstatus.c
+ **/
+
 #ifndef TOR_NETSTATUS_H
 #define TOR_NETSTATUS_H
 
diff --git a/src/core/mainloop/periodic.h b/src/core/mainloop/periodic.h
index 0f80748f55..34fb9cc5ae 100644
--- a/src/core/mainloop/periodic.h
+++ b/src/core/mainloop/periodic.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2015-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file periodic.h
+ * @brief Header for periodic.c
+ **/
+
 #ifndef TOR_PERIODIC_H
 #define TOR_PERIODIC_H
 
diff --git a/src/core/or/addr_policy_st.h b/src/core/or/addr_policy_st.h
index 11442d29b4..41c4ac47eb 100644
--- a/src/core/or/addr_policy_st.h
+++ b/src/core/or/addr_policy_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file addr_policy_st.h
+ * @brief Address policy structures.
+ **/
+
 #ifndef TOR_ADDR_POLICY_ST_H
 #define TOR_ADDR_POLICY_ST_H
 
diff --git a/src/core/or/cell_queue_st.h b/src/core/or/cell_queue_st.h
index 7ba339b965..763bc5bc1e 100644
--- a/src/core/or/cell_queue_st.h
+++ b/src/core/or/cell_queue_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file cell_queue_st.h
+ * @brief Cell queue structures
+ **/
+
 #ifndef PACKED_CELL_ST_H
 #define PACKED_CELL_ST_H
 
diff --git a/src/core/or/cell_st.h b/src/core/or/cell_st.h
index c4eec4f4b5..5c1667d321 100644
--- a/src/core/or/cell_st.h
+++ b/src/core/or/cell_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file cell_st.h
+ * @brief Fixed-size cell structure.
+ **/
+
 #ifndef CELL_ST_H
 #define CELL_ST_H
 
@@ -17,4 +22,3 @@ struct cell_t {
 };
 
 #endif /* !defined(CELL_ST_H) */
-
diff --git a/src/core/or/channelpadding.c b/src/core/or/channelpadding.c
index 4a0f0e00da..2b8314db89 100644
--- a/src/core/or/channelpadding.c
+++ b/src/core/or/channelpadding.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file channelpadding.c
+ * @brief Link-level padding code.
+ **/
+
 /* TOR_CHANNEL_INTERNAL_ define needed for an O(1) implementation of
  * channelpadding_channel_to_channelinfo() */
 #define TOR_CHANNEL_INTERNAL_
diff --git a/src/core/or/circuit_st.h b/src/core/or/circuit_st.h
index eae3c908d5..0c281f7257 100644
--- a/src/core/or/circuit_st.h
+++ b/src/core/or/circuit_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file circuit_st.h
+ * @brief Base circuit structure.
+ **/
+
 #ifndef CIRCUIT_ST_H
 #define CIRCUIT_ST_H
 
diff --git a/src/core/or/connection_st.h b/src/core/or/connection_st.h
index 1c42a56d6b..08558d79ff 100644
--- a/src/core/or/connection_st.h
+++ b/src/core/or/connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file connection_st.h
+ * @brief Base connection structure.
+ **/
+
 #ifndef CONNECTION_ST_H
 #define CONNECTION_ST_H
 
diff --git a/src/core/or/cpath_build_state_st.h b/src/core/or/cpath_build_state_st.h
index 4572a10430..240badde40 100644
--- a/src/core/or/cpath_build_state_st.h
+++ b/src/core/or/cpath_build_state_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file cpath_build_state_st.h
+ * @brief Circuit-build-stse structure
+ **/
+
 #ifndef CIRCUIT_BUILD_STATE_ST_ST_H
 #define CIRCUIT_BUILD_STATE_ST_ST_H
 
@@ -35,4 +40,3 @@ struct cpath_build_state_t {
 };
 
 #endif /* !defined(CIRCUIT_BUILD_STATE_ST_ST_H) */
-
diff --git a/src/core/or/crypt_path_reference_st.h b/src/core/or/crypt_path_reference_st.h
index 1827022b4e..fb20a3fc5a 100644
--- a/src/core/or/crypt_path_reference_st.h
+++ b/src/core/or/crypt_path_reference_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file crypt_path_reference_st.h
+ * @brief reference-counting structure for crypt_path_t
+ **/
+
 #ifndef CRYPT_PATH_REFERENCE_ST_H
 #define CRYPT_PATH_REFERENCE_ST_H
 
@@ -20,4 +25,3 @@ struct crypt_path_reference_t {
 };
 
 #endif /* !defined(CRYPT_PATH_REFERENCE_ST_H) */
-
diff --git a/src/core/or/crypt_path_st.h b/src/core/or/crypt_path_st.h
index 249ac6aaa3..945961d5d1 100644
--- a/src/core/or/crypt_path_st.h
+++ b/src/core/or/crypt_path_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file crypt_path_st.h
+ * @brief Path structures for origin circuits.
+ **/
+
 #ifndef CRYPT_PATH_ST_H
 #define CRYPT_PATH_ST_H
 
diff --git a/src/core/or/destroy_cell_queue_st.h b/src/core/or/destroy_cell_queue_st.h
index e917afc700..fc817c1b42 100644
--- a/src/core/or/destroy_cell_queue_st.h
+++ b/src/core/or/destroy_cell_queue_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file destroy_cell_queue_st.h
+ * @brief Destroy-cell queue structures
+ **/
+
 #ifndef DESTROY_CELL_QUEUE_ST_H
 #define DESTROY_CELL_QUEUE_ST_H
 
@@ -24,4 +29,3 @@ struct destroy_cell_queue_t {
 };
 
 #endif /* !defined(DESTROY_CELL_QUEUE_ST_H) */
-
diff --git a/src/core/or/edge_connection_st.h b/src/core/or/edge_connection_st.h
index 8922a3a9cf..d043d1ffb4 100644
--- a/src/core/or/edge_connection_st.h
+++ b/src/core/or/edge_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file edge_connection_st.h
+ * @brief Edge-connection structure.
+ **/
+
 #ifndef EDGE_CONNECTION_ST_H
 #define EDGE_CONNECTION_ST_H
 
@@ -74,4 +79,3 @@ struct edge_connection_t {
 };
 
 #endif /* !defined(EDGE_CONNECTION_ST_H) */
-
diff --git a/src/core/or/entry_connection_st.h b/src/core/or/entry_connection_st.h
index e65c545d17..b866e78493 100644
--- a/src/core/or/entry_connection_st.h
+++ b/src/core/or/entry_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file entry_connection_st.h
+ * @brief Entry connection structure.
+ **/
+
 #ifndef ENTRY_CONNECTION_ST_H
 #define ENTRY_CONNECTION_ST_H
 
@@ -97,4 +102,3 @@ struct entry_connection_t {
 #define ENTRY_TO_EDGE_CONN(c) (&(((c))->edge_))
 
 #endif /* !defined(ENTRY_CONNECTION_ST_H) */
-
diff --git a/src/core/or/entry_port_cfg_st.h b/src/core/or/entry_port_cfg_st.h
index b84838d44f..f52f47d1c9 100644
--- a/src/core/or/entry_port_cfg_st.h
+++ b/src/core/or/entry_port_cfg_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file entry_port_cfg_st.h
+ * @brief Configuration structure for client ports.
+ **/
+
 #ifndef ENTRY_PORT_CFG_ST_H
 #define ENTRY_PORT_CFG_ST_H
 
@@ -51,4 +56,3 @@ struct entry_port_cfg_t {
 };
 
 #endif /* !defined(ENTRY_PORT_CFG_ST_H) */
-
diff --git a/src/core/or/extend_info_st.h b/src/core/or/extend_info_st.h
index 7704ff16b5..babf15c59a 100644
--- a/src/core/or/extend_info_st.h
+++ b/src/core/or/extend_info_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file extend_info_st.h
+ * @brief Extend-info structure.
+ **/
+
 #ifndef EXTEND_INFO_ST_H
 #define EXTEND_INFO_ST_H
 
diff --git a/src/core/or/half_edge_st.h b/src/core/or/half_edge_st.h
index 1fe47ad3f1..cb2044654f 100644
--- a/src/core/or/half_edge_st.h
+++ b/src/core/or/half_edge_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file half_edge_st.h
+ * @brief Half-open connection structure.
+ **/
+
 #ifndef HALF_EDGE_ST_H
 #define HALF_EDGE_ST_H
 
@@ -31,4 +36,3 @@ typedef struct half_edge_t {
 } half_edge_t;
 
 #endif /* !defined(HALF_EDGE_ST_H) */
-
diff --git a/src/core/or/listener_connection_st.h b/src/core/or/listener_connection_st.h
index 1250d9c9b4..fafc8444f9 100644
--- a/src/core/or/listener_connection_st.h
+++ b/src/core/or/listener_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file listener_connection_st.h
+ * @brief Listener connection structure.
+ **/
+
 #ifndef LISTENER_CONNECTION_ST_H
 #define LISTENER_CONNECTION_ST_H
 
@@ -22,4 +27,3 @@ struct listener_connection_t {
 };
 
 #endif /* !defined(LISTENER_CONNECTION_ST_H) */
-
diff --git a/src/core/or/or_connection_st.h b/src/core/or/or_connection_st.h
index 051fcd00d3..c364117a35 100644
--- a/src/core/or/or_connection_st.h
+++ b/src/core/or/or_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file or_connection_st.h
+ * @brief OR connection structure.
+ **/
+
 #ifndef OR_CONNECTION_ST_H
 #define OR_CONNECTION_ST_H
 
diff --git a/src/core/or/or_handshake_certs_st.h b/src/core/or/or_handshake_certs_st.h
index 9deb6d6d59..209fee551d 100644
--- a/src/core/or/or_handshake_certs_st.h
+++ b/src/core/or/or_handshake_certs_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file or_handshake_certs_st.h
+ * @brief OR handshake certs structure
+ **/
+
 #ifndef OR_HANDSHAKE_CERTS_ST
 #define OR_HANDSHAKE_CERTS_ST
 
diff --git a/src/core/or/or_handshake_state_st.h b/src/core/or/or_handshake_state_st.h
index 472ce8a302..43f88e7565 100644
--- a/src/core/or/or_handshake_state_st.h
+++ b/src/core/or/or_handshake_state_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file or_handshake_state_st.h
+ * @brief OR handshake state structure
+ **/
+
 #ifndef OR_HANDSHAKE_STATE_ST
 #define OR_HANDSHAKE_STATE_ST
 
@@ -75,4 +80,3 @@ struct or_handshake_state_t {
 };
 
 #endif /* !defined(OR_HANDSHAKE_STATE_ST) */
-
diff --git a/src/core/or/origin_circuit_st.h b/src/core/or/origin_circuit_st.h
index 01bbc84ae2..cdb3f95a99 100644
--- a/src/core/or/origin_circuit_st.h
+++ b/src/core/or/origin_circuit_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file origin_circuit_st.h
+ * @brief Origin circuit structure.
+ **/
+
 #ifndef ORIGIN_CIRCUIT_ST_H
 #define ORIGIN_CIRCUIT_ST_H
 
diff --git a/src/core/or/port_cfg_st.h b/src/core/or/port_cfg_st.h
index e9e82bb1de..f27c81d951 100644
--- a/src/core/or/port_cfg_st.h
+++ b/src/core/or/port_cfg_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file port_cfg_st.h
+ * @brief Listener port configuration structure.
+ **/
+
 #ifndef PORT_CFG_ST_H
 #define PORT_CFG_ST_H
 
@@ -32,4 +37,3 @@ struct port_cfg_t {
 };
 
 #endif /* !defined(PORT_CFG_ST_H) */
-
diff --git a/src/core/or/relay_crypto_st.h b/src/core/or/relay_crypto_st.h
index 83bbd329a6..1b1eb16df1 100644
--- a/src/core/or/relay_crypto_st.h
+++ b/src/core/or/relay_crypto_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file relay_crypto_st.h
+ * @brief Relay-cell encryption state structure.
+ **/
+
 #ifndef RELAY_CRYPTO_ST_H
 #define RELAY_CRYPTO_ST_H
 
diff --git a/src/core/or/scheduler_kist.c b/src/core/or/scheduler_kist.c
index 35b613cb8a..f4bac7b877 100644
--- a/src/core/or/scheduler_kist.c
+++ b/src/core/or/scheduler_kist.c
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file scheduler_kist.c
+ * @brief Implements the KIST cell scheduler.
+ **/
+
 #define SCHEDULER_KIST_PRIVATE
 
 #include "core/or/or.h"
diff --git a/src/core/or/scheduler_vanilla.c b/src/core/or/scheduler_vanilla.c
index 33536ae04b..bd84a4e4ef 100644
--- a/src/core/or/scheduler_vanilla.c
+++ b/src/core/or/scheduler_vanilla.c
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file scheduler_vanilla.c
+ * @brief "Vanilla" (pre-KIST) cell scheduler code.
+ **/
+
 #include "core/or/or.h"
 #include "app/config/config.h"
 #define TOR_CHANNEL_INTERNAL_
@@ -172,4 +177,3 @@ get_vanilla_scheduler(void)
 {
   return &vanilla_scheduler;
 }
-
diff --git a/src/core/or/server_port_cfg_st.h b/src/core/or/server_port_cfg_st.h
index 0738735c61..c160576714 100644
--- a/src/core/or/server_port_cfg_st.h
+++ b/src/core/or/server_port_cfg_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file server_port_cfg_st.h
+ * @brief Cnfiguration structure for server ports.
+ **/
+
 #ifndef SERVER_PORT_CFG_ST_H
 #define SERVER_PORT_CFG_ST_H
 
@@ -17,4 +22,3 @@ struct server_port_cfg_t {
 };
 
 #endif /* !defined(SERVER_PORT_CFG_ST_H) */
-
diff --git a/src/core/or/socks_request_st.h b/src/core/or/socks_request_st.h
index 9fb941ff7e..2931543ee2 100644
--- a/src/core/or/socks_request_st.h
+++ b/src/core/or/socks_request_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file socks_request_st.h
+ * @brief Client request structure.
+ **/
+
 #ifndef SOCKS_REQUEST_ST_H
 #define SOCKS_REQUEST_ST_H
 
diff --git a/src/core/or/status.h b/src/core/or/status.h
index 3467501ebb..3568f39d6d 100644
--- a/src/core/or/status.h
+++ b/src/core/or/status.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2010-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file status.h
+ * @brief Header for status.c
+ **/
+
 #ifndef TOR_STATUS_H
 #define TOR_STATUS_H
 
@@ -15,4 +20,3 @@ STATIC char *bytes_to_usage(uint64_t bytes);
 #endif
 
 #endif /* !defined(TOR_STATUS_H) */
-
diff --git a/src/core/or/tor_version_st.h b/src/core/or/tor_version_st.h
index c5bdcaf07b..c3ef00b960 100644
--- a/src/core/or/tor_version_st.h
+++ b/src/core/or/tor_version_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file tor_version_st.h
+ * @brief Parsed Tor version structure.
+ **/
+
 #ifndef TOR_VERSION_ST_H
 #define TOR_VERSION_ST_H
 
@@ -29,4 +34,3 @@ struct tor_version_t {
 };
 
 #endif /* !defined(TOR_VERSION_ST_H) */
-
diff --git a/src/core/or/var_cell_st.h b/src/core/or/var_cell_st.h
index 607c0d6c83..5c847202a9 100644
--- a/src/core/or/var_cell_st.h
+++ b/src/core/or/var_cell_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file var_cell_st.h
+ * @brief Variable-length cell structure.
+ **/
+
 #ifndef VAR_CELL_ST_H
 #define VAR_CELL_ST_H
 
@@ -20,4 +25,3 @@ struct var_cell_t {
 };
 
 #endif /* !defined(VAR_CELL_ST_H) */
-
diff --git a/src/core/proto/proto_cell.c b/src/core/proto/proto_cell.c
index 697fed29e1..aed94b4ff1 100644
--- a/src/core/proto/proto_cell.c
+++ b/src/core/proto/proto_cell.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_cell.c
+ * @brief Decodes Tor cells from buffers.
+ **/
+/* Right now it only handles variable-length cells, but eventually
+ * we should refactor other cell-reading code into here. */
+
 #include "core/or/or.h"
 #include "lib/buf/buffers.h"
 #include "core/proto/proto_cell.h"
@@ -83,4 +90,3 @@ fetch_var_cell_from_buf(buf_t *buf, var_cell_t **out, int linkproto)
   *out = result;
   return 1;
 }
-
diff --git a/src/core/proto/proto_cell.h b/src/core/proto/proto_cell.h
index 4f3982ea43..b5bfb09c49 100644
--- a/src/core/proto/proto_cell.h
+++ b/src/core/proto/proto_cell.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_cell.h
+ * @brief Header for proto_cell.c
+ **/
+
 #ifndef TOR_PROTO_CELL_H
 #define TOR_PROTO_CELL_H
 
@@ -14,4 +19,3 @@ int fetch_var_cell_from_buf(struct buf_t *buf, struct var_cell_t **out,
                             int linkproto);
 
 #endif /* !defined(TOR_PROTO_CELL_H) */
-
diff --git a/src/core/proto/proto_control0.c b/src/core/proto/proto_control0.c
index d741f28f09..3aa6a814f2 100644
--- a/src/core/proto/proto_control0.c
+++ b/src/core/proto/proto_control0.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_control0.c
+ * @brief Code to detect the obsolete v0 control protocol.
+ **/
+
 #include "core/or/or.h"
 #include "lib/buf/buffers.h"
 #include "core/proto/proto_control0.h"
@@ -23,4 +28,3 @@ peek_buf_has_control0_command(buf_t *buf)
   }
   return 0;
 }
-
diff --git a/src/core/proto/proto_control0.h b/src/core/proto/proto_control0.h
index 162e513a1b..ecb834bfba 100644
--- a/src/core/proto/proto_control0.h
+++ b/src/core/proto/proto_control0.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_control0.h
+ * @brief Header for proto_control0.c
+ **/
+
 #ifndef TOR_PROTO_CONTROL0_H
 #define TOR_PROTO_CONTROL0_H
 
@@ -11,4 +16,3 @@ struct buf_t;
 int peek_buf_has_control0_command(struct buf_t *buf);
 
 #endif /* !defined(TOR_PROTO_CONTROL0_H) */
-
diff --git a/src/core/proto/proto_ext_or.c b/src/core/proto/proto_ext_or.c
index 4213bc14dd..db491e352d 100644
--- a/src/core/proto/proto_ext_or.c
+++ b/src/core/proto/proto_ext_or.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_ext_or.c
+ * @brief Parsing/encoding for the extended OR protocol.
+ **/
+
 #include "core/or/or.h"
 #include "lib/buf/buffers.h"
 #include "feature/relay/ext_orport.h"
@@ -37,4 +42,3 @@ fetch_ext_or_command_from_buf(buf_t *buf, ext_or_cmd_t **out)
   buf_get_bytes(buf, (*out)->body, len);
   return 1;
 }
-
diff --git a/src/core/proto/proto_ext_or.h b/src/core/proto/proto_ext_or.h
index b2bc64af85..de3fbdb814 100644
--- a/src/core/proto/proto_ext_or.h
+++ b/src/core/proto/proto_ext_or.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_ext_or.h
+ * @brief Header for proto_ext_or.c
+ **/
+
 #ifndef TOR_PROTO_EXT_OR_H
 #define TOR_PROTO_EXT_OR_H
 
diff --git a/src/core/proto/proto_http.c b/src/core/proto/proto_http.c
index 88c59ef561..2668bdcc7d 100644
--- a/src/core/proto/proto_http.c
+++ b/src/core/proto/proto_http.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_http.c
+ * @brief Parse a subset of the HTTP protocol.
+ **/
+
 #define PROTO_HTTP_PRIVATE
 #include "core/or/or.h"
 #include "lib/buf/buffers.h"
@@ -168,4 +173,3 @@ buf_http_find_content_length(const char *headers, size_t headerlen,
 
   return ok ? 1 : -1;
 }
-
diff --git a/src/core/proto/proto_http.h b/src/core/proto/proto_http.h
index cd70050205..6f38f99067 100644
--- a/src/core/proto/proto_http.h
+++ b/src/core/proto/proto_http.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_http.h
+ * @brief Header for proto_http.c
+ **/
+
 #ifndef TOR_PROTO_HTTP_H
 #define TOR_PROTO_HTTP_H
 
@@ -21,4 +26,3 @@ STATIC int buf_http_find_content_length(const char *headers, size_t headerlen,
 #endif
 
 #endif /* !defined(TOR_PROTO_HTTP_H) */
-
diff --git a/src/core/proto/proto_socks.c b/src/core/proto/proto_socks.c
index b657a7b758..e48b373382 100644
--- a/src/core/proto/proto_socks.c
+++ b/src/core/proto/proto_socks.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_socks.c
+ * @brief Implementations for SOCKS4 and SOCKS5 protocols.
+ **/
+
 #include "core/or/or.h"
 #include "feature/client/addressmap.h"
 #include "lib/buf/buffers.h"
@@ -105,7 +110,7 @@ socks_request_free_(socks_request_t *req)
 /**
  * Parse a single SOCKS4 request from buffer <b>raw_data</b> of length
  * <b>datalen</b> and update relevant fields of <b>req</b>. If SOCKS4a
- * request is detected, set <b>*is_socks4a<b> to true. Set <b>*drain_out</b>
+ * request is detected, set <b>*is_socks4a</b> to true. Set <b>*drain_out</b>
  * to number of bytes we parsed so far.
  *
  * Return SOCKS_RESULT_DONE if parsing succeeded, SOCKS_RESULT_INVALID if
diff --git a/src/core/proto/proto_socks.h b/src/core/proto/proto_socks.h
index 2a387bf848..a29df92f64 100644
--- a/src/core/proto/proto_socks.h
+++ b/src/core/proto/proto_socks.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proto_socks.h
+ * @brief Header for proto_socks.c
+ **/
+
 #ifndef TOR_PROTO_SOCKS_H
 #define TOR_PROTO_SOCKS_H
 
diff --git a/src/feature/api/tor_api_internal.h b/src/feature/api/tor_api_internal.h
index 60e0f3aa59..115d33d58e 100644
--- a/src/feature/api/tor_api_internal.h
+++ b/src/feature/api/tor_api_internal.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file tor_api_internal.h
+ * @brief Internal declarations for in-process Tor API.
+ **/
+
 #ifndef TOR_API_INTERNAL_H
 #define TOR_API_INTERNAL_H
 
diff --git a/src/feature/client/addressmap.h b/src/feature/client/addressmap.h
index 9179aef1d0..eb9742c50b 100644
--- a/src/feature/client/addressmap.h
+++ b/src/feature/client/addressmap.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file addressmap.h
+ * @brief Header for addressmap.c
+ **/
+
 #ifndef TOR_ADDRESSMAP_H
 #define TOR_ADDRESSMAP_H
 
@@ -62,4 +67,3 @@ STATIC void get_random_virtual_addr(const virtual_addr_conf_t *conf,
 #endif /* defined(ADDRESSMAP_PRIVATE) */
 
 #endif /* !defined(TOR_ADDRESSMAP_H) */
-
diff --git a/src/feature/client/proxymode.c b/src/feature/client/proxymode.c
index 3b5fba5cda..0682205336 100644
--- a/src/feature/client/proxymode.c
+++ b/src/feature/client/proxymode.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file proxymode.c
+ * @brief Determine whether we are trying to be a proxy.
+ **/
+
 #include "core/or/or.h"
 
 #include "app/config/config.h"
diff --git a/src/feature/control/control_connection_st.h b/src/feature/control/control_connection_st.h
index c9164f03b3..8ecce5ee69 100644
--- a/src/feature/control/control_connection_st.h
+++ b/src/feature/control/control_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file control_connection_st.h
+ * @brief Controller connection structure.
+ **/
+
 #ifndef CONTROL_CONNECTION_ST_H
 #define CONTROL_CONNECTION_ST_H
 
diff --git a/src/feature/control/fmt_serverstatus.c b/src/feature/control/fmt_serverstatus.c
index 33c5ba1336..92db70758f 100644
--- a/src/feature/control/fmt_serverstatus.c
+++ b/src/feature/control/fmt_serverstatus.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file fmt_serverstatus.c
+ * @brief Format relay info for a controller.
+ **/
+
 #include "core/or/or.h"
 #include "feature/control/fmt_serverstatus.h"
 
diff --git a/src/feature/control/getinfo_geoip.c b/src/feature/control/getinfo_geoip.c
index d188725fa3..4636ede039 100644
--- a/src/feature/control/getinfo_geoip.c
+++ b/src/feature/control/getinfo_geoip.c
@@ -1,3 +1,12 @@
+/* Copyright (c) 2001-2004, Roger Dingledine.
+ * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
+ * Copyright (c) 2007-2019, The Tor Project, Inc. */
+/* See LICENSE for licensing information */
+
+/**
+ * @file getinfo_geoip.c
+ * @brief GEOIP-related contoller GETINFO commands.
+ **/
 
 #include "core/or/or.h"
 #include "core/mainloop/connection.h"
diff --git a/src/feature/control/getinfo_geoip.h b/src/feature/control/getinfo_geoip.h
index 94759d0d18..f6bc86cb53 100644
--- a/src/feature/control/getinfo_geoip.h
+++ b/src/feature/control/getinfo_geoip.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file getinfo_geoip.h
+ * @brief Header for getinfo_geoip.c
+ **/
+
 #ifndef TOR_GETINFO_GEOIP_H
 #define TOR_GETINFO_GEOIP_H
 
diff --git a/src/feature/dirauth/bridgeauth.c b/src/feature/dirauth/bridgeauth.c
index 4aaefc7a6d..56782011c2 100644
--- a/src/feature/dirauth/bridgeauth.c
+++ b/src/feature/dirauth/bridgeauth.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file bridgeauth.c
+ * @brief Bridge authority code
+ **/
+
 #include "core/or/or.h"
 #include "feature/dirauth/bridgeauth.h"
 #include "feature/dirauth/voteflags.h"
diff --git a/src/feature/dirauth/bridgeauth.h b/src/feature/dirauth/bridgeauth.h
index 4905e9c3ee..76676e8db5 100644
--- a/src/feature/dirauth/bridgeauth.h
+++ b/src/feature/dirauth/bridgeauth.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file bridgeauth.h
+ * @brief Header for bridgeauth.c
+ **/
+
 #ifndef TOR_DIRAUTH_BRIDGEAUTH_H
 #define TOR_DIRAUTH_BRIDGEAUTH_H
 
diff --git a/src/feature/dirauth/dirauth_periodic.c b/src/feature/dirauth/dirauth_periodic.c
index fc26358290..96194b4677 100644
--- a/src/feature/dirauth/dirauth_periodic.c
+++ b/src/feature/dirauth/dirauth_periodic.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dirauth_periodic.c
+ * @brief Peridoic events for directory authorities.
+ **/
+
 #include "core/or/or.h"
 
 #include "app/config/or_options_st.h"
diff --git a/src/feature/dirauth/dirauth_periodic.h b/src/feature/dirauth/dirauth_periodic.h
index 866fbd35de..de4a799d37 100644
--- a/src/feature/dirauth/dirauth_periodic.h
+++ b/src/feature/dirauth/dirauth_periodic.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dirauth_periodic.h
+ * @brief Header for dirauth_periodic.c
+ **/
+
 #ifndef DIRVOTE_PERIODIC_H
 #define DIRVOTE_PERIODIC_H
 
diff --git a/src/feature/dirauth/dirauth_sys.c b/src/feature/dirauth/dirauth_sys.c
index e38d391300..090e9129f2 100644
--- a/src/feature/dirauth/dirauth_sys.c
+++ b/src/feature/dirauth/dirauth_sys.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dirauth_sys.c
+ * @brief Directory authority subsystem declarations
+ **/
+
 #include "core/or/or.h"
 
 #include "feature/dirauth/bwauth.h"
diff --git a/src/feature/dirauth/dirauth_sys.h b/src/feature/dirauth/dirauth_sys.h
index 4e9b6a2ab4..2d5a0cb3e7 100644
--- a/src/feature/dirauth/dirauth_sys.h
+++ b/src/feature/dirauth/dirauth_sys.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dirauth_sys.h
+ * @brief Header for dirauth_sys.c
+ **/
+
 #ifndef DIRAUTH_SYS_H
 #define DIRAUTH_SYS_H
 
diff --git a/src/feature/dirauth/keypin.h b/src/feature/dirauth/keypin.h
index 1de84f6d4a..d77f6fc5f3 100644
--- a/src/feature/dirauth/keypin.h
+++ b/src/feature/dirauth/keypin.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2014-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file keypin.h
+ * @brief Header for keypin.c
+ **/
+
 #ifndef TOR_KEYPIN_H
 #define TOR_KEYPIN_H
 
diff --git a/src/feature/dirauth/ns_detached_signatures_st.h b/src/feature/dirauth/ns_detached_signatures_st.h
index 61d20b7525..7c50cda40a 100644
--- a/src/feature/dirauth/ns_detached_signatures_st.h
+++ b/src/feature/dirauth/ns_detached_signatures_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file ns_detached_signatures_st.h
+ * @brief Detached consensus signatures structure.
+ **/
+
 #ifndef NS_DETACHED_SIGNATURES_ST_H
 #define NS_DETACHED_SIGNATURES_ST_H
 
@@ -19,4 +24,3 @@ struct ns_detached_signatures_t {
 };
 
 #endif /* !defined(NS_DETACHED_SIGNATURES_ST_H) */
-
diff --git a/src/feature/dirauth/shared_random_state.h b/src/feature/dirauth/shared_random_state.h
index f6bcddd088..74792967a7 100644
--- a/src/feature/dirauth/shared_random_state.h
+++ b/src/feature/dirauth/shared_random_state.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2016-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file shared_random_state.h
+ * @brief Header for shared_random_state.c
+ **/
+
 #ifndef TOR_SHARED_RANDOM_STATE_H
 #define TOR_SHARED_RANDOM_STATE_H
 
diff --git a/src/feature/dirauth/vote_microdesc_hash_st.h b/src/feature/dirauth/vote_microdesc_hash_st.h
index 7869f92b4f..24c7443b36 100644
--- a/src/feature/dirauth/vote_microdesc_hash_st.h
+++ b/src/feature/dirauth/vote_microdesc_hash_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file vote_microdesc_hash_st.h
+ * @brief Microdescriptor-hash voting strcture.
+ **/
+
 #ifndef VOTE_MICRODESC_HASH_ST_H
 #define VOTE_MICRODESC_HASH_ST_H
 
@@ -19,4 +24,3 @@ struct vote_microdesc_hash_t {
 };
 
 #endif /* !defined(VOTE_MICRODESC_HASH_ST_H) */
-
diff --git a/src/feature/dircache/cached_dir_st.h b/src/feature/dircache/cached_dir_st.h
index a28802f905..e086f5b11d 100644
--- a/src/feature/dircache/cached_dir_st.h
+++ b/src/feature/dircache/cached_dir_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file cached_dir_st.h
+ * @brief Cached large directory object structure.
+ **/
+
 #ifndef CACHED_DIR_ST_H
 #define CACHED_DIR_ST_H
 
@@ -22,4 +27,3 @@ struct cached_dir_t {
 };
 
 #endif /* !defined(CACHED_DIR_ST_H) */
-
diff --git a/src/feature/dircache/conscache.c b/src/feature/dircache/conscache.c
index 2ec9981c03..903fa5bc0a 100644
--- a/src/feature/dircache/conscache.c
+++ b/src/feature/dircache/conscache.c
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file conscache.c
+ * @brief Consensus and diff on-disk cache.
+ **/
+
 #include "core/or/or.h"
 
 #include "app/config/config.h"
@@ -246,7 +251,7 @@ consensus_cache_find_first(consensus_cache_t *cache,
 }
 
 /**
- * Given a <b>cache</b>, add every entry to <b>out<b> for which
+ * Given a <b>cache</b>, add every entry to <b>out</b> for which
  * <b>key</b>=<b>value</b>.  If <b>key</b> is NULL, add every entry.
  *
  * Do not add any entry that has been marked for removal.
diff --git a/src/feature/dircache/conscache.h b/src/feature/dircache/conscache.h
index d848e57617..54c081c068 100644
--- a/src/feature/dircache/conscache.h
+++ b/src/feature/dircache/conscache.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file conscache.h
+ * @brief Header for conscache.c
+ **/
+
 #ifndef TOR_CONSCACHE_H
 #define TOR_CONSCACHE_H
 
diff --git a/src/feature/dircache/consdiffmgr.h b/src/feature/dircache/consdiffmgr.h
index b1b3323b6c..7222353650 100644
--- a/src/feature/dircache/consdiffmgr.h
+++ b/src/feature/dircache/consdiffmgr.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2017-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file consdiffmgr.h
+ * @brief Header for consdiffmgr.c
+ **/
+
 #ifndef TOR_CONSDIFFMGR_H
 #define TOR_CONSDIFFMGR_H
 
diff --git a/src/feature/dircache/dircache.c b/src/feature/dircache/dircache.c
index d4d0ad9939..795f1b8ed7 100644
--- a/src/feature/dircache/dircache.c
+++ b/src/feature/dircache/dircache.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dircache.c
+ * @brief Cache directories and serve them to clients.
+ **/
+
 #define DIRCACHE_PRIVATE
 
 #include "core/or/or.h"
@@ -560,7 +565,7 @@ parse_one_diff_hash(uint8_t *digest, const char *hex, const char *location,
 }
 
 /** If there is an X-Or-Diff-From-Consensus header included in <b>headers</b>,
- * set <b>digest_out<b> to a new smartlist containing every 256-bit
+ * set <b>digest_out</b> to a new smartlist containing every 256-bit
  * hex-encoded digest listed in that header and return 0.  Otherwise return
  * -1.  */
 static int
@@ -1379,7 +1384,7 @@ handle_get_hs_descriptor_v2(dir_connection_t *conn,
   return 0;
 }
 
-/** Helper function for GET /tor/hs/3/<z>. Only for version 3.
+/** Helper function for GET `/tor/hs/3/...`. Only for version 3.
  */
 STATIC int
 handle_get_hs_descriptor_v3(dir_connection_t *conn,
diff --git a/src/feature/dirclient/dir_server_st.h b/src/feature/dirclient/dir_server_st.h
index 8e35532435..69c3856185 100644
--- a/src/feature/dirclient/dir_server_st.h
+++ b/src/feature/dirclient/dir_server_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dir_server_st.h
+ * @brief Trusted/fallback directory server structure.
+ **/
+
 #ifndef DIR_SERVER_ST_H
 #define DIR_SERVER_ST_H
 
diff --git a/src/feature/dirclient/dirclient.c b/src/feature/dirclient/dirclient.c
index 1ea50fd350..a97b425944 100644
--- a/src/feature/dirclient/dirclient.c
+++ b/src/feature/dirclient/dirclient.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dirclient.c
+ * @brief Download directory information
+ **/
+
 #define DIRCLIENT_PRIVATE
 
 #include "core/or/or.h"
diff --git a/src/feature/dirclient/dlstatus.c b/src/feature/dirclient/dlstatus.c
index 0842a2c676..c6fdbebed9 100644
--- a/src/feature/dirclient/dlstatus.c
+++ b/src/feature/dirclient/dlstatus.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dlstatus.c
+ * @brief Track status and retry schedule of a downloadable object.
+ **/
+
 #define DLSTATUS_PRIVATE
 
 #include "core/or/or.h"
diff --git a/src/feature/dirclient/download_status_st.h b/src/feature/dirclient/download_status_st.h
index 39a5ad2860..29d0dd5d5f 100644
--- a/src/feature/dirclient/download_status_st.h
+++ b/src/feature/dirclient/download_status_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file download_status_st.h
+ * @brief Directory download status/schedule structure.
+ **/
+
 #ifndef DOWNLOAD_STATUS_ST_H
 #define DOWNLOAD_STATUS_ST_H
 
@@ -62,4 +67,3 @@ struct download_status_t {
 };
 
 #endif /* !defined(DOWNLOAD_STATUS_ST_H) */
-
diff --git a/src/feature/dircommon/consdiff.h b/src/feature/dircommon/consdiff.h
index b63fcb2cc6..0e8c4b4d8e 100644
--- a/src/feature/dircommon/consdiff.h
+++ b/src/feature/dircommon/consdiff.h
@@ -2,6 +2,11 @@
  * Copyright (c) 2014-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file consdiff.h
+ * @brief Header for consdiff.c
+ **/
+
 #ifndef TOR_CONSDIFF_H
 #define TOR_CONSDIFF_H
 
diff --git a/src/feature/dircommon/dir_connection_st.h b/src/feature/dircommon/dir_connection_st.h
index a858560c29..ba978e142a 100644
--- a/src/feature/dircommon/dir_connection_st.h
+++ b/src/feature/dircommon/dir_connection_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dir_connection_st.h
+ * @brief Client/server directory connection structure.
+ **/
+
 #ifndef DIR_CONNECTION_ST_H
 #define DIR_CONNECTION_ST_H
 
diff --git a/src/feature/dircommon/vote_timing_st.h b/src/feature/dircommon/vote_timing_st.h
index 814a325314..352a69b2dd 100644
--- a/src/feature/dircommon/vote_timing_st.h
+++ b/src/feature/dircommon/vote_timing_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file vote_timing_st.h
+ * @brief Directory voting schedule structure.
+ **/
+
 #ifndef VOTE_TIMING_ST_H
 #define VOTE_TIMING_ST_H
 
@@ -21,4 +26,3 @@ struct vote_timing_t {
 };
 
 #endif /* !defined(VOTE_TIMING_ST_H) */
-
diff --git a/src/feature/dirparse/authcert_parse.c b/src/feature/dirparse/authcert_parse.c
index d22293e281..b18e1159f3 100644
--- a/src/feature/dirparse/authcert_parse.c
+++ b/src/feature/dirparse/authcert_parse.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file authcert_parse.c
+ * @brief Authority certificate parsing.
+ **/
+
 #include "core/or/or.h"
 #include "feature/dirparse/authcert_parse.h"
 #include "feature/dirparse/parsecommon.h"
diff --git a/src/feature/dirparse/unparseable.c b/src/feature/dirparse/unparseable.c
index 941b5a1f6d..3b96df9e30 100644
--- a/src/feature/dirparse/unparseable.c
+++ b/src/feature/dirparse/unparseable.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file unparseable.c
+ * @brief Dump unparseable objects to disk.
+ **/
+
 #define UNPARSEABLE_PRIVATE
 
 #include "core/or/or.h"
diff --git a/src/feature/hs/hsdir_index_st.h b/src/feature/hs/hsdir_index_st.h
index 6c86c02f47..34ff84f91f 100644
--- a/src/feature/hs/hsdir_index_st.h
+++ b/src/feature/hs/hsdir_index_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file hsdir_index_st.h
+ * @brief HS directory index structure
+ **/
+
 #ifndef HSDIR_INDEX_ST_H
 #define HSDIR_INDEX_ST_H
 
@@ -21,4 +26,3 @@ struct hsdir_index_t {
 };
 
 #endif /* !defined(HSDIR_INDEX_ST_H) */
-
diff --git a/src/feature/nodelist/authority_cert_st.h b/src/feature/nodelist/authority_cert_st.h
index bf9b690c24..6787487c7c 100644
--- a/src/feature/nodelist/authority_cert_st.h
+++ b/src/feature/nodelist/authority_cert_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file authority_cert_st.h
+ * @brief Authority certificate structure.
+ **/
+
 #ifndef AUTHORITY_CERT_ST_H
 #define AUTHORITY_CERT_ST_H
 
@@ -29,4 +34,3 @@ struct authority_cert_t {
 };
 
 #endif /* !defined(AUTHORITY_CERT_ST_H) */
-
diff --git a/src/feature/nodelist/desc_store_st.h b/src/feature/nodelist/desc_store_st.h
index 4d1378cdfa..75300ecf97 100644
--- a/src/feature/nodelist/desc_store_st.h
+++ b/src/feature/nodelist/desc_store_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file desc_store_st.h
+ * @brief Routerinfo/extrainfo storage structure.
+ **/
+
 #ifndef DESC_STORE_ST_H
 #define DESC_STORE_ST_H
 
diff --git a/src/feature/nodelist/document_signature_st.h b/src/feature/nodelist/document_signature_st.h
index ac2a803252..ba4581c1b8 100644
--- a/src/feature/nodelist/document_signature_st.h
+++ b/src/feature/nodelist/document_signature_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file document_signature_st.h
+ * @brief Authority signature structure
+ **/
+
 #ifndef DOCUMENT_SIGNATURE_ST_H
 #define DOCUMENT_SIGNATURE_ST_H
 
@@ -26,4 +31,3 @@ struct document_signature_t {
 };
 
 #endif /* !defined(DOCUMENT_SIGNATURE_ST_H) */
-
diff --git a/src/feature/nodelist/extrainfo_st.h b/src/feature/nodelist/extrainfo_st.h
index 22c708f018..6d707bea05 100644
--- a/src/feature/nodelist/extrainfo_st.h
+++ b/src/feature/nodelist/extrainfo_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file extrainfo_st.h
+ * @brief A relay's extra-info structure.
+ **/
+
 #ifndef EXTRAINFO_ST_H
 #define EXTRAINFO_ST_H
 
@@ -27,4 +32,3 @@ struct extrainfo_t {
 };
 
 #endif /* !defined(EXTRAINFO_ST_H) */
-
diff --git a/src/feature/nodelist/microdesc_st.h b/src/feature/nodelist/microdesc_st.h
index e017c46c79..58b0630573 100644
--- a/src/feature/nodelist/microdesc_st.h
+++ b/src/feature/nodelist/microdesc_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file microdesc_st.h
+ * @brief Microdescriptor structure
+ **/
+
 #ifndef MICRODESC_ST_H
 #define MICRODESC_ST_H
 
diff --git a/src/feature/nodelist/networkstatus_sr_info_st.h b/src/feature/nodelist/networkstatus_sr_info_st.h
index 420c3d61e4..1392fa6853 100644
--- a/src/feature/nodelist/networkstatus_sr_info_st.h
+++ b/src/feature/nodelist/networkstatus_sr_info_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file networkstatus_sr_info_st.h
+ * @brief Shared-randomness structure.
+ **/
+
 #ifndef NETWORKSTATUS_SR_INFO_ST_H
 #define NETWORKSTATUS_SR_INFO_ST_H
 
@@ -20,4 +25,3 @@ struct networkstatus_sr_info_t {
 };
 
 #endif /* !defined(NETWORKSTATUS_SR_INFO_ST_H) */
-
diff --git a/src/feature/nodelist/networkstatus_st.h b/src/feature/nodelist/networkstatus_st.h
index 6e84c170d6..a23ef0c193 100644
--- a/src/feature/nodelist/networkstatus_st.h
+++ b/src/feature/nodelist/networkstatus_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file networkstatus_st.h
+ * @brief Networkstatus consensus/vote structure.
+ **/
+
 #ifndef NETWORKSTATUS_ST_H
 #define NETWORKSTATUS_ST_H
 
diff --git a/src/feature/nodelist/networkstatus_voter_info_st.h b/src/feature/nodelist/networkstatus_voter_info_st.h
index 66af82a8e3..629cb52254 100644
--- a/src/feature/nodelist/networkstatus_voter_info_st.h
+++ b/src/feature/nodelist/networkstatus_voter_info_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file networkstatus_voter_info_st.h
+ * @brief Single consensus voter structure.
+ **/
+
 #ifndef NETWORKSTATUS_VOTER_INFO_ST_H
 #define NETWORKSTATUS_VOTER_INFO_ST_H
 
diff --git a/src/feature/nodelist/node_st.h b/src/feature/nodelist/node_st.h
index c63a535a19..6ad10bb85a 100644
--- a/src/feature/nodelist/node_st.h
+++ b/src/feature/nodelist/node_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file node_st.h
+ * @brief Node information structure.
+ **/
+
 #ifndef NODE_ST_H
 #define NODE_ST_H
 
diff --git a/src/feature/nodelist/nodefamily_st.h b/src/feature/nodelist/nodefamily_st.h
index 20390c9308..4aa00b0255 100644
--- a/src/feature/nodelist/nodefamily_st.h
+++ b/src/feature/nodelist/nodefamily_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file nodefamily_st.h
+ * @brief Compact node-family structure
+ **/
+
 #ifndef TOR_NODEFAMILY_ST_H
 #define TOR_NODEFAMILY_ST_H
 
diff --git a/src/feature/nodelist/routerinfo.c b/src/feature/nodelist/routerinfo.c
index 975b503615..4e570fcbb2 100644
--- a/src/feature/nodelist/routerinfo.c
+++ b/src/feature/nodelist/routerinfo.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routerinfo.c
+ * @brief Manipulate full router descriptors.
+ **/
+
 #include "core/or/or.h"
 
 #include "feature/nodelist/nodelist.h"
diff --git a/src/feature/nodelist/routerinfo_st.h b/src/feature/nodelist/routerinfo_st.h
index 59fd56d0a0..16387f1005 100644
--- a/src/feature/nodelist/routerinfo_st.h
+++ b/src/feature/nodelist/routerinfo_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routerinfo_st.h
+ * @brief Router descriptor structure.
+ **/
+
 #ifndef ROUTERINFO_ST_H
 #define ROUTERINFO_ST_H
 
diff --git a/src/feature/nodelist/routerlist_st.h b/src/feature/nodelist/routerlist_st.h
index 10b919a1bf..d3a3874983 100644
--- a/src/feature/nodelist/routerlist_st.h
+++ b/src/feature/nodelist/routerlist_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routerlist_st.h
+ * @brief Router descriptor list structure.
+ **/
+
 #ifndef ROUTERLIST_ST_H
 #define ROUTERLIST_ST_H
 
@@ -37,4 +42,3 @@ struct routerlist_t {
 };
 
 #endif /* !defined(ROUTERLIST_ST_H) */
-
diff --git a/src/feature/nodelist/routerstatus_st.h b/src/feature/nodelist/routerstatus_st.h
index 46337c9e52..b60e0e41d0 100644
--- a/src/feature/nodelist/routerstatus_st.h
+++ b/src/feature/nodelist/routerstatus_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routerstatus_st.h
+ * @brief Routerstatus (consensus entry) structure
+ **/
+
 #ifndef ROUTERSTATUS_ST_H
 #define ROUTERSTATUS_ST_H
 
@@ -79,4 +84,3 @@ struct routerstatus_t {
 };
 
 #endif /* !defined(ROUTERSTATUS_ST_H) */
-
diff --git a/src/feature/nodelist/signed_descriptor_st.h b/src/feature/nodelist/signed_descriptor_st.h
index 64c28f7440..952fc702f4 100644
--- a/src/feature/nodelist/signed_descriptor_st.h
+++ b/src/feature/nodelist/signed_descriptor_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file signed_descriptor_st.h
+ * @brief Descriptor/extrainfo signature structure
+ **/
+
 #ifndef SIGNED_DESCRIPTOR_ST_H
 #define SIGNED_DESCRIPTOR_ST_H
 
@@ -58,4 +63,3 @@ struct signed_descriptor_t {
 };
 
 #endif /* !defined(SIGNED_DESCRIPTOR_ST_H) */
-
diff --git a/src/feature/nodelist/torcert.h b/src/feature/nodelist/torcert.h
index 03d5bdca93..5a1f932392 100644
--- a/src/feature/nodelist/torcert.h
+++ b/src/feature/nodelist/torcert.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2014-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file torcert.h
+ * @brief Header for torcert.c
+ **/
+
 #ifndef TORCERT_H_INCLUDED
 #define TORCERT_H_INCLUDED
 
diff --git a/src/feature/nodelist/vote_routerstatus_st.h b/src/feature/nodelist/vote_routerstatus_st.h
index 0d909da260..e34b5e5f69 100644
--- a/src/feature/nodelist/vote_routerstatus_st.h
+++ b/src/feature/nodelist/vote_routerstatus_st.h
@@ -4,6 +4,10 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file vote_routerstatus_st.h
+ * @brief Routerstatus (vote entry) structure
+ **/
 #ifndef VOTE_ROUTERSTATUS_ST_H
 #define VOTE_ROUTERSTATUS_ST_H
 
diff --git a/src/feature/relay/ext_orport.h b/src/feature/relay/ext_orport.h
index 7313ebd03d..a981ca80c2 100644
--- a/src/feature/relay/ext_orport.h
+++ b/src/feature/relay/ext_orport.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file ext_orport.h
+ * @brief Header for ext_orport.c
+ **/
+
 #ifndef EXT_ORPORT_H
 #define EXT_ORPORT_H
 
diff --git a/src/feature/relay/routerkeys.h b/src/feature/relay/routerkeys.h
index cde07b52c3..d2860718b2 100644
--- a/src/feature/relay/routerkeys.h
+++ b/src/feature/relay/routerkeys.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2014-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routerkeys.h
+ * @brief Header for routerkeys.c
+ **/
+
 #ifndef TOR_ROUTERKEYS_H
 #define TOR_ROUTERKEYS_H
 
diff --git a/src/feature/relay/routermode.c b/src/feature/relay/routermode.c
index 3613841b1e..92bcfaf8fa 100644
--- a/src/feature/relay/routermode.c
+++ b/src/feature/relay/routermode.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file routermode.c
+ * @brief Check if we're running as a relay/cache.
+ **/
+
 #include "core/or/or.h"
 
 #include "app/config/config.h"
diff --git a/src/feature/rend/rend_authorized_client_st.h b/src/feature/rend/rend_authorized_client_st.h
index 51a1798fcb..0819f2134a 100644
--- a/src/feature/rend/rend_authorized_client_st.h
+++ b/src/feature/rend/rend_authorized_client_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file rend_authorized_client_st.h
+ * @brief Hidden-service authorized client structure.
+ **/
+
 #ifndef REND_AUTHORIZED_CLIENT_ST_H
 #define REND_AUTHORIZED_CLIENT_ST_H
 
@@ -15,4 +20,3 @@ struct rend_authorized_client_t {
 };
 
 #endif /* !defined(REND_AUTHORIZED_CLIENT_ST_H) */
-
diff --git a/src/feature/rend/rend_encoded_v2_service_descriptor_st.h b/src/feature/rend/rend_encoded_v2_service_descriptor_st.h
index bd8a60f0d9..5eec600fd1 100644
--- a/src/feature/rend/rend_encoded_v2_service_descriptor_st.h
+++ b/src/feature/rend/rend_encoded_v2_service_descriptor_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file rend_encoded_v2_service_descriptor_st.h
+ * @brief Encoded v2 HS descriptor structure.
+ **/
+
 #ifndef REND_ENCODED_V2_SERVICE_DESCRIPTOR_ST_H
 #define REND_ENCODED_V2_SERVICE_DESCRIPTOR_ST_H
 
@@ -14,4 +19,3 @@ struct rend_encoded_v2_service_descriptor_t {
 };
 
 #endif /* !defined(REND_ENCODED_V2_SERVICE_DESCRIPTOR_ST_H) */
-
diff --git a/src/feature/rend/rend_intro_point_st.h b/src/feature/rend/rend_intro_point_st.h
index 4882b62752..9acf155708 100644
--- a/src/feature/rend/rend_intro_point_st.h
+++ b/src/feature/rend/rend_intro_point_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file rend_intro_point_st.h
+ * @brief v2 hidden service introduction point structure.
+ **/
+
 #ifndef REND_INTRO_POINT_ST_H
 #define REND_INTRO_POINT_ST_H
 
diff --git a/src/feature/rend/rend_service_descriptor_st.h b/src/feature/rend/rend_service_descriptor_st.h
index ff7627ce96..bdfe87dcae 100644
--- a/src/feature/rend/rend_service_descriptor_st.h
+++ b/src/feature/rend/rend_service_descriptor_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file rend_service_descriptor_st.h
+ * @brief Parsed v2 HS descriptor structure.
+ **/
+
 #ifndef REND_SERVICE_DESCRIPTOR_ST_H
 #define REND_SERVICE_DESCRIPTOR_ST_H
 
@@ -31,4 +36,3 @@ struct rend_service_descriptor_t {
 };
 
 #endif /* !defined(REND_SERVICE_DESCRIPTOR_ST_H) */
-
diff --git a/src/lib/container/namemap.c b/src/lib/container/namemap.c
index a90057b32c..909dcc9f03 100644
--- a/src/lib/container/namemap.c
+++ b/src/lib/container/namemap.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file namemap.c
+ * @brief Mappings between identifiers and 16-bit ints.
+ **/
+
 #include "orconfig.h"
 #include "lib/container/smartlist.h"
 #include "lib/container/namemap.h"
diff --git a/src/lib/container/namemap_st.h b/src/lib/container/namemap_st.h
index 2fa73fc173..20a8051918 100644
--- a/src/lib/container/namemap_st.h
+++ b/src/lib/container/namemap_st.h
@@ -6,6 +6,11 @@
 #ifndef NAMEMAP_ST_H
 #define NAMEMAP_ST_H
 
+/**
+ * @file namemap_st.h
+ * @brief Internal declarations for namemap structure.
+ **/
+
 #include "lib/cc/compat_compiler.h"
 #include "ext/ht.h"
 
diff --git a/src/lib/crypt_ops/crypto_ope.c b/src/lib/crypt_ops/crypto_ope.c
index ed832d852e..e4fef319e9 100644
--- a/src/lib/crypt_ops/crypto_ope.c
+++ b/src/lib/crypt_ops/crypto_ope.c
@@ -2,7 +2,8 @@
 /* See LICENSE for licensing information */
 
 /**
- * A rudimentary order-preserving encryption scheme.
+ * @file crypto_ope.c
+ * @brief A rudimentary order-preserving encryption scheme.
  *
  * To compute the encryption of N, this scheme uses an AES-CTR stream to
  * generate M-byte values, and adds the first N of them together. (+1 each to
@@ -143,7 +144,7 @@ crypto_ope_new(const uint8_t *key)
   return ope;
 }
 
-/** Free all storage held in <>ope</b>. */
+/** Free all storage held in <b>ope</b>. */
 void
 crypto_ope_free_(crypto_ope_t *ope)
 {
diff --git a/src/lib/crypt_ops/crypto_ope.h b/src/lib/crypt_ops/crypto_ope.h
index 9778dfe0f0..d6a81dbcc1 100644
--- a/src/lib/crypt_ops/crypto_ope.h
+++ b/src/lib/crypt_ops/crypto_ope.h
@@ -1,6 +1,11 @@
 /* Copyright (c) 2018-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file crypto_ope.h
+ * @brief header for crypto_ope.c
+ **/
+
 #ifndef CRYPTO_OPE_H
 #define CRYPTO_OPE_H
 
diff --git a/src/lib/dispatch/dispatch_cfg.h b/src/lib/dispatch/dispatch_cfg.h
index 348dce8d40..929ec54215 100644
--- a/src/lib/dispatch/dispatch_cfg.h
+++ b/src/lib/dispatch/dispatch_cfg.h
@@ -7,6 +7,11 @@
 #ifndef TOR_DISPATCH_CFG_H
 #define TOR_DISPATCH_CFG_H
 
+/**
+ * @file dispatch_cfg.h
+ * @brief Header for distpach_cfg.c
+ **/
+
 #include "lib/dispatch/msgtypes.h"
 #include "lib/testsupport/testsupport.h"
 
diff --git a/src/lib/dispatch/dispatch_cfg_st.h b/src/lib/dispatch/dispatch_cfg_st.h
index 57b6f0347f..d06540c4a9 100644
--- a/src/lib/dispatch/dispatch_cfg_st.h
+++ b/src/lib/dispatch/dispatch_cfg_st.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dispatch_cfg_st.h
+ * @brief Declarations for dispatch-configuration types.
+ **/
+
 #ifndef TOR_DISPATCH_CFG_ST_H
 #define TOR_DISPATCH_CFG_ST_H
 
diff --git a/src/lib/dispatch/dispatch_naming.c b/src/lib/dispatch/dispatch_naming.c
index e8e28cc71e..c501aa34bd 100644
--- a/src/lib/dispatch/dispatch_naming.c
+++ b/src/lib/dispatch/dispatch_naming.c
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dispatch_naming.c
+ * @brief Name-to-ID maps for our message dispatch system.
+ **/
+
 #include "orconfig.h"
 
 #include "lib/cc/compat_compiler.h"
diff --git a/src/lib/dispatch/dispatch_naming.h b/src/lib/dispatch/dispatch_naming.h
index fd6c83cc12..d36851bce9 100644
--- a/src/lib/dispatch/dispatch_naming.h
+++ b/src/lib/dispatch/dispatch_naming.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file dispatch_naming.h
+ * @brief Header for dispatch_naming.c
+ **/
+
 #ifndef TOR_DISPATCH_NAMING_H
 #define TOR_DISPATCH_NAMING_H
 
diff --git a/src/lib/geoip/country.h b/src/lib/geoip/country.h
index a24a1c4c0d..2bff4f4477 100644
--- a/src/lib/geoip/country.h
+++ b/src/lib/geoip/country.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file country.h
+ * @brief Country type for geoip.
+ **/
+
 #ifndef TOR_COUNTRY_H
 #define TOR_COUNTRY_H
 
diff --git a/src/lib/net/socketpair.c b/src/lib/net/socketpair.c
index f3a0c3770a..aa88c58266 100644
--- a/src/lib/net/socketpair.c
+++ b/src/lib/net/socketpair.c
@@ -2,6 +2,11 @@
  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 
+/**
+ * @file socketpair.c
+ * @brief Replacement socketpair() for systems that lack it
+ **/
+
 #include "lib/cc/torint.h"
 #include "lib/net/socketpair.h"
 #include "lib/net/inaddr_st.h"
diff --git a/src/lib/net/socketpair.h b/src/lib/net/socketpair.h
index 5820606973..c2e99d505e 100644
--- a/src/lib/net/socketpair.h
+++ b/src/lib/net/socketpair.h
@@ -6,6 +6,11 @@
 #ifndef TOR_SOCKETPAIR_H
 #define TOR_SOCKETPAIR_H
 
+/**
+ * @file socketpair.h
+ * @brief Header for socketpair.c
+ **/
+
 #include "orconfig.h"
 #include "lib/testsupport/testsupport.h"
 #include "lib/net/nettypes.h"
diff --git a/src/lib/pubsub/pubsub_publish.h b/src/lib/pubsub/pubsub_publish.h
index 0686a465de..6369725405 100644
--- a/src/lib/pubsub/pubsub_publish.h
+++ b/src/lib/pubsub/pubsub_publish.h
@@ -4,6 +4,11 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file pubsub_publish.h
+ * @brief Header for pubsub_publish.c
+ **/
+
 #ifndef TOR_PUBSUB_PUBLISH_H
 #define TOR_PUBSUB_PUBLISH_H
 
diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h
index 21f984f32d..35a30680ee 100644
--- a/src/lib/subsys/subsys.h
+++ b/src/lib/subsys/subsys.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file subsys.h
+ * @brief Types used to declare a subsystem.
+ **/
+
 #ifndef TOR_SUBSYS_T
 #define TOR_SUBSYS_T
 
diff --git a/src/lib/tls/tortls.c b/src/lib/tls/tortls.c
index 1aff40c437..f3c117efa3 100644
--- a/src/lib/tls/tortls.c
+++ b/src/lib/tls/tortls.c
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file tortls.c
+ * @brief Shared functionality for our TLS backends.
+ **/
+
 #define TORTLS_PRIVATE
 #define TOR_X509_PRIVATE
 #include "lib/tls/x509.h"
diff --git a/src/lib/tls/tortls_internal.h b/src/lib/tls/tortls_internal.h
index 866483a94c..a7aee524f3 100644
--- a/src/lib/tls/tortls_internal.h
+++ b/src/lib/tls/tortls_internal.h
@@ -3,6 +3,11 @@
  * Copyright (c) 2007-2019, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * @file tortls_internal.h
+ * @brief Declare internal functions for lib/tls
+ **/
+
 #ifndef TORTLS_INTERNAL_H
 #define TORTLS_INTERNAL_H
 
diff --git a/src/lib/tls/tortls_st.h b/src/lib/tls/tortls_st.h
index 73f6e6ecca..37935894f3 100644
--- a/src/lib/tls/tortls_st.h
+++ b/src/lib/tls/tortls_st.h
@@ -6,6 +6,14 @@
 #ifndef TOR_TORTLS_ST_H
 #define TOR_TORTLS_ST_H
 
+/**
+ * @file tortls_st.h
+ * @brief Structure declarations for internal TLS types.
+ *
+ * These should generally be treated as opaque outside of the
+ * lib/tls module.
+ **/
+
 #include "lib/net/socket.h"
 
 #define TOR_TLS_MAGIC 0x71571571
diff --git a/src/lib/version/git_revision.c b/src/lib/version/git_revision.c
index 6cfb3b4ec0..e87620a20c 100644
--- a/src/lib/version/git_revision.c
+++ b/src/lib/version/git_revision.c
@@ -6,6 +6,11 @@
 #include "orconfig.h"
 #include "lib/version/git_revision.h"
 
+/**
+ * @file git_revision.c
+ * @brief Strings to describe the current Git commit.
+ **/
+
 /** String describing which Tor Git repository version the source was
  * built from.  This string is generated by a bit of shell kludging in
  * src/core/include.am, and is usually right.
diff --git a/src/lib/version/git_revision.h b/src/lib/version/git_revision.h
index 79e3c6684b..5d08e84b84 100644
--- a/src/lib/version/git_revision.h
+++ b/src/lib/version/git_revision.h
@@ -6,6 +6,11 @@
 #ifndef TOR_GIT_REVISION_H
 #define TOR_GIT_REVISION_H
 
+/**
+ * @file git_revision.h
+ * @brief Header for git_revision.c
+ **/
+
 extern const char tor_git_revision[];
 extern const char tor_bug_suffix[];
 
diff --git a/src/lib/version/torversion.h b/src/lib/version/torversion.h
index 7b0fb66ec0..50d646bd23 100644
--- a/src/lib/version/torversion.h
+++ b/src/lib/version/torversion.h
@@ -6,6 +6,11 @@
 #ifndef TOR_VERSION_H
 #define TOR_VERSION_H
 
+/**
+ * @file torversion.h
+ * @brief Header for version.c.
+ **/
+
 const char *get_version(void);
 const char *get_short_version(void);
 
diff --git a/src/lib/version/version.c b/src/lib/version/version.c
index 434e6fb424..b2f25e97b5 100644
--- a/src/lib/version/version.c
+++ b/src/lib/version/version.c
@@ -10,6 +10,11 @@
 #include <stdio.h>
 #include <string.h>
 
+/**
+ * @file version.c
+ * @brief Functions to get the version of Tor.
+ **/
+
 /** A shorter version of this Tor process's version, for export in our router
  *  descriptor.  (Does not include the git version, if any.) */
 static const char the_short_tor_version[] =