[tor-commits] [tor/master] Add a brief file-level description for everything in src/common

[nickm at torproject.org]

commit 23f8c9b32fc8515b7666b10167b9a1104a20de3e
Author: Nick Mathewson <nickm at torproject.org>
Date:   Sat Feb 27 18:19:57 2016 +0100

    Add a brief file-level description for everything in src/common
---
 src/common/backtrace.c         | 7 +++++++
 src/common/compat_pthreads.c   | 7 +++++++
 src/common/compat_threads.c    | 8 ++++++++
 src/common/compat_winthreads.c | 7 +++++++
 src/common/crypto_curve25519.c | 6 +++++-
 src/common/crypto_ed25519.c    | 6 +++++-
 src/common/crypto_format.c     | 6 +++++-
 src/common/crypto_pwbox.c      | 9 +++++++++
 src/common/crypto_s2k.c        | 6 ++++++
 src/common/util_format.c       | 7 +++++++
 src/common/workqueue.c         | 7 +++++++
 11 files changed, 73 insertions(+), 3 deletions(-)

diff --git a/src/common/backtrace.c b/src/common/backtrace.c
index 94de1eb..f7b5dc2 100644
--- a/src/common/backtrace.c
+++ b/src/common/backtrace.c
@@ -1,6 +1,13 @@
 /* Copyright (c) 2013-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file backtrace.c
+ *
+ * \brief Functions to produce backtraces on bugs, crashes, or assertion
+ * failures.
+ */
+
 #define __USE_GNU
 #define _GNU_SOURCE 1
 
diff --git a/src/common/compat_pthreads.c b/src/common/compat_pthreads.c
index b1d87d3..b59f097 100644
--- a/src/common/compat_pthreads.c
+++ b/src/common/compat_pthreads.c
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_pthreads.c
+ *
+ * \brief Implementation for the pthreads-based multithreading backend
+ * functions.
+ */
+
 #define _GNU_SOURCE
 
 #include "orconfig.h"
diff --git a/src/common/compat_threads.c b/src/common/compat_threads.c
index 85ad737..848b10a 100644
--- a/src/common/compat_threads.c
+++ b/src/common/compat_threads.c
@@ -3,6 +3,14 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_threads.c
+ *
+ * \brief Cross-platform threading and inter-thread communication logic.
+ *  (Platform-specific parts are written in the other compat_*threads
+ *  modules.)
+ */
+
 #define _GNU_SOURCE
 
 #include "orconfig.h"
diff --git a/src/common/compat_winthreads.c b/src/common/compat_winthreads.c
index 9a87daa..ba0b641 100644
--- a/src/common/compat_winthreads.c
+++ b/src/common/compat_winthreads.c
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file compat_winthreads.c
+ *
+ * \brief Implementation for the windows-based multithreading backend
+ * functions.
+ */
+
 #ifdef _WIN32
 
 #include "compat.h"
diff --git a/src/common/crypto_curve25519.c b/src/common/crypto_curve25519.c
index 2002483..47a93bf 100644
--- a/src/common/crypto_curve25519.c
+++ b/src/common/crypto_curve25519.c
@@ -1,7 +1,11 @@
 /* Copyright (c) 2012-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
-/* Wrapper code for a curve25519 implementation. */
+/**
+ * \file crypto_curve25519.c
+ *
+ * \brief Wrapper code for a curve25519 implementation.
+ */
 
 #define CRYPTO_CURVE25519_PRIVATE
 #include "orconfig.h"
diff --git a/src/common/crypto_ed25519.c b/src/common/crypto_ed25519.c
index 9df665f..3409b7f 100644
--- a/src/common/crypto_ed25519.c
+++ b/src/common/crypto_ed25519.c
@@ -1,7 +1,11 @@
 /* Copyright (c) 2013-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
-/* Wrapper code for an ed25519 implementation. */
+/**
+ * \file crypto_ed25519.c
+ *
+ * \brief Wrapper code for an ed25519 implementation.
+ */
 
 #include "orconfig.h"
 #ifdef HAVE_SYS_STAT_H
diff --git a/src/common/crypto_format.c b/src/common/crypto_format.c
index d4ecd5b..422ebb5 100644
--- a/src/common/crypto_format.c
+++ b/src/common/crypto_format.c
@@ -4,7 +4,11 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
-/* Formatting and parsing code for crypto-related data structures. */
+/**
+ * \file crypto_format.c
+ *
+ * \brief Formatting and parsing code for crypto-related data structures.
+ */
 
 #include "orconfig.h"
 #ifdef HAVE_SYS_STAT_H
diff --git a/src/common/crypto_pwbox.c b/src/common/crypto_pwbox.c
index b866c7e..819dc0c 100644
--- a/src/common/crypto_pwbox.c
+++ b/src/common/crypto_pwbox.c
@@ -1,3 +1,12 @@
+/* Copyright (c) 2014-2016, The Tor Project, Inc. */
+/* See LICENSE for licensing information */
+
+/**
+ * \file crypto_pwbox.c
+ *
+ * \brief Code for encrypting secrets in a password-protected form and saving
+ * them to disk.
+ */
 
 #include "crypto.h"
 #include "crypto_s2k.h"
diff --git a/src/common/crypto_s2k.c b/src/common/crypto_s2k.c
index 99f3b2e..6dd791e 100644
--- a/src/common/crypto_s2k.c
+++ b/src/common/crypto_s2k.c
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file crypto_s2k.c
+ *
+ * \brief Functions for deriving keys from human-readable passphrases.
+ */
+
 #define CRYPTO_S2K_PRIVATE
 
 #include "crypto.h"
diff --git a/src/common/util_format.c b/src/common/util_format.c
index 8d99138..476e098 100644
--- a/src/common/util_format.c
+++ b/src/common/util_format.c
@@ -4,6 +4,13 @@
  * Copyright (c) 2007-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file util_format.c
+ *
+ * \brief Miscellaneous functions for encoding and decoding various things
+ *   in base{16,32,64}.
+ */
+
 #include "orconfig.h"
 #include "torlog.h"
 #include "util.h"
diff --git a/src/common/workqueue.c b/src/common/workqueue.c
index c467bdf..0a38550 100644
--- a/src/common/workqueue.c
+++ b/src/common/workqueue.c
@@ -1,6 +1,13 @@
 /* copyright (c) 2013-2015, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file workqueue.c
+ *
+ * \brief Implements worker threads, queues of work for them, and mechanisms
+ * for them to send answers back to the main thread.
+ */
+
 #include "orconfig.h"
 #include "compat.h"
 #include "compat_threads.h"