commit 23f8c9b32fc8515b7666b10167b9a1104a20de3e Author: Nick Mathewson <nickm@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"