doxygen: add @file declarations for src/lib

If a file doesn't use the file command (either \file or @file),
Doxygen won't try to process it.

These declarations also turned up a doxygen warning for
crypto_ope.c; I fixed that too.

diff --git a/src/lib/container/namemap.c b/src/lib/container/namemap.c
index a90057b32ce55206cc741988ec5e735223d0ea5b..909dcc9f031a795d6f6e297f735246ab7ee40f67 100644 (file)
--- 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 2fa73fc173b39545e09e83ad593a491b553c3352..20a8051918de04499481d5556c424c15b0b0eca1 100644 (file)
--- 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 ed832d852e95602fe5a0b5eb3a6635eb816edd51..e4fef319e9c28200de6018765163732188d07305 100644 (file)
--- 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 9778dfe0f08ab290b78bda05fa4e69867fbe20bd..d6a81dbcc10744aef617e03096914df3b7db0fe6 100644 (file)
--- 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 348dce8d40a2d0d7c728e2bf03ee5a1ab6fba251..929ec54215870f4ff84ed2c08f114aa352047dd6 100644 (file)
--- 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 57b6f0347f500ff658310e1bddf3498549fcb8c7..d06540c4a9812b2b6cca1d9303f518e5961c42cf 100644 (file)
--- 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 e8e28cc71e18ccf14ba81df319fe0e5d92b929bd..c501aa34bd7b09251942b18d7273163e825b5767 100644 (file)
--- 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 fd6c83cc12f338dc41bc14fe9f4844535f42e6b1..d36851bce9873b97856a36a601581380b21aedd2 100644 (file)
--- 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 a24a1c4c0de6862be316c6e9c6255bbe9376acb2..2bff4f44775283741caa7f64e9df239800dcde73 100644 (file)
--- 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 f3a0c3770ae323264803182b9e11487e75d2cb39..aa88c58266d8c745b2315a2dba8c3442d8c5d6c2 100644 (file)
--- 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 58206069736f0df2d84408d1e0ec4ee42d3f911f..c2e99d505e2625fe02a7ac6f4e9008055e6d3797 100644 (file)
--- 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 0686a465de0b2948e27770fdb6faaeab990c0b3b..63697254054a70bb27dacaf2e78939284235d288 100644 (file)
--- 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 21f984f32d6e0eba7e4f70fd191461b1f773af0f..35a30680eece77dde79700e9c7c3f81aa1834619 100644 (file)
--- 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 1aff40c43766647107453fec13b88fa8d820183c..f3c117efa373d1e580e4734c1d800684e20f7689 100644 (file)
--- 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 866483a94ced7ca0d372aa29a2399b540823423a..a7aee524f3f75c3423d342e4e57ed589599606ba 100644 (file)
--- 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 73f6e6ecca8dfcc413b52c30175134ec7e6de0d5..37935894f3f0266838d1b4a054f2cc5b6daf5cf5 100644 (file)
--- 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 6cfb3b4ec097355a9bcfc7b87db10dd444845c6a..e87620a20c53ac24936a684fa2441bab20e67d13 100644 (file)
--- 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 79e3c6684b687b23e441e05a8f0b9ecf7cf78ed1..5d08e84b844bf694aec797107a1eaad438159287 100644 (file)
--- 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 7b0fb66ec0bbf0420f7f53a7888777d0b9ad9649..50d646bd232eb5efba518ba41467355f0f89f994 100644 (file)
--- 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 434e6fb42436ef9f9c864023315e0556111be293..b2f25e97b52cd7c0937f840f1558ef6e18f7866e 100644 (file)
--- 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[] =