[tor-commits] [tor/master] doxygen: add @file declarations for src/lib
dgoulet at torproject.org
dgoulet at torproject.org
Mon Oct 28 12:51:12 UTC 2019
commit 39d09ea0810f74a7666d9d694903780a14b48ca2
Author: Nick Mathewson <nickm at torproject.org>
Date: Sat Oct 26 11:13:29 2019 -0400
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.
---
src/lib/container/namemap.c | 5 +++++
src/lib/container/namemap_st.h | 5 +++++
src/lib/crypt_ops/crypto_ope.c | 5 +++--
src/lib/crypt_ops/crypto_ope.h | 5 +++++
src/lib/dispatch/dispatch_cfg.h | 5 +++++
src/lib/dispatch/dispatch_cfg_st.h | 5 +++++
src/lib/dispatch/dispatch_naming.c | 5 +++++
src/lib/dispatch/dispatch_naming.h | 5 +++++
src/lib/geoip/country.h | 5 +++++
src/lib/net/socketpair.c | 5 +++++
src/lib/net/socketpair.h | 5 +++++
src/lib/pubsub/pubsub_publish.h | 5 +++++
src/lib/subsys/subsys.h | 5 +++++
src/lib/tls/tortls.c | 5 +++++
src/lib/tls/tortls_internal.h | 5 +++++
src/lib/tls/tortls_st.h | 8 ++++++++
src/lib/version/git_revision.c | 5 +++++
src/lib/version/git_revision.h | 5 +++++
src/lib/version/torversion.h | 5 +++++
src/lib/version/version.c | 5 +++++
20 files changed, 101 insertions(+), 2 deletions(-)
diff --git a/src/lib/container/namemap.c b/src/lib/container/namemap.c
index a90057b32..909dcc9f0 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 2fa73fc17..20a805191 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 ed832d852..e4fef319e 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 9778dfe0f..d6a81dbcc 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 348dce8d4..929ec5421 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 57b6f0347..d06540c4a 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 e8e28cc71..c501aa34b 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 fd6c83cc1..d36851bce 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 a24a1c4c0..2bff4f447 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 f3a0c3770..aa88c5826 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 582060697..c2e99d505 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 0686a465d..636972540 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 21f984f32..35a30680e 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 1aff40c43..f3c117efa 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 866483a94..a7aee524f 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 73f6e6ecc..37935894f 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 6cfb3b4ec..e87620a20 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 79e3c6684..5d08e84b8 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 7b0fb66ec..50d646bd2 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 434e6fb42..b2f25e97b 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[] =
More information about the tor-commits
mailing list