[tor-commits] [obfsproxy/master] Add brief file-level documentation for all source files.

commit 6016f54a961d51fe8a2fc2bbee18d41d0127d092 Author: George Kadianakis desnacked@gmail.com Date: Sun Dec 11 05:18:59 2011 +0100

Add brief file-level documentation for all source files. --- Doxyfile | 2 +- src/container.h | 5 +++++ src/crypt.c | 6 ++++++ src/crypt.h | 5 +++++ src/external.c | 6 ++++++ src/external.h | 5 +++++ src/ht.h | 5 +++++ src/main.c | 11 +++++++++++ src/main.h | 6 ++++++ src/managed.c | 6 ++++++ src/managed.h | 5 +++++ src/network.c | 8 ++++++++ src/network.h | 5 +++++ src/obfs_main.c | 6 ++++++ src/protocol.c | 9 +++++++++ src/protocol.h | 5 +++++ src/protocols/dummy.c | 7 +++++++ src/protocols/dummy.h | 6 ++++++ src/protocols/obfs2.c | 7 +++++++ src/protocols/obfs2.h | 5 +++++ src/sha256.c | 13 ++++++++++--- src/sha256.h | 8 +++++++- src/socks.c | 6 ++++++ src/socks.h | 5 +++++ src/test/tester.py.in | 14 ++++++++------ src/util.c | 6 ++++++ src/util.h | 5 +++++ 27 files changed, 166 insertions(+), 11 deletions(-)

diff --git a/Doxyfile b/Doxyfile index ba1d24a..a479ab2 100644 --- a/Doxyfile +++ b/Doxyfile @@ -534,7 +534,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces.

-INPUT = src/ +INPUT = src/ src/protocols/

# This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/src/container.h b/src/container.h index 129e4f9..ff5b9e2 100644 --- a/src/container.h +++ b/src/container.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2011, The Tor Project, Inc. */ /* See LICENSE for licensing information */

+/** + * \file container.h + * \brief Headers for container.c. + **/ + #ifndef CONTAINER_H #define CONTAINER_H

diff --git a/src/crypt.c b/src/crypt.c index 62d99fe..b8240be 100644 --- a/src/crypt.c +++ b/src/crypt.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file crypt.c + * \headerfile crypt.h + * \brief Cryptographic functions. + **/ + #include "util.h"

#define CRYPT_PRIVATE diff --git a/src/crypt.h b/src/crypt.h index 51bbc57..bf20803 100644 --- a/src/crypt.h +++ b/src/crypt.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file crypt.h + * \brief Headers for crypt.c. + **/ + #ifndef CRYPT_H #define CRYPT_H

diff --git a/src/external.c b/src/external.c index e05deca..3a79909 100644 --- a/src/external.c +++ b/src/external.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file external.c + * \headerfile external.h + * \brief Implements the 'external proxy' mode of obfsproxy. + **/ + #include "util.h"

#include "container.h" diff --git a/src/external.h b/src/external.h index 6bfcb46..d9d987c 100644 --- a/src/external.h +++ b/src/external.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file external.h + * \brief Headers for external.c. + **/ + #ifndef EXTERNAL_H #define EXTERNAL_H

diff --git a/src/ht.h b/src/ht.h index 8c45db1..6733612 100644 --- a/src/ht.h +++ b/src/ht.h @@ -3,6 +3,11 @@ * Copyright (c) 2007-2011, The Tor Project, Inc. */ /* See license at end. */

+/** + * \file ht.h + * \brief Hash table functions. + **/ + /* Based on ideas by Christopher Clark and interfaces from Niels Provos. */

#ifndef HT_H diff --git a/src/main.c b/src/main.c index c7515a2..e03daf0 100644 --- a/src/main.c +++ b/src/main.c @@ -2,6 +2,17 @@ See LICENSE for other credits and copying information */

+/** + * \file main.c + * \headerfile main.h + * \brief Entry point of obfsproxy. Does command-line parsing, and + * switches into 'external' or 'managed' proxy mode. + * + * (Practically, obfs_main.c is the actual entry point of obfsproxy, + * but all it does is call obfs_main().) + **/ + + #include "util.h"

#include "container.h" diff --git a/src/main.h b/src/main.h index 538cfdd..65900b3 100644 --- a/src/main.h +++ b/src/main.h @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file main.h + * \brief Headers for main.c. + **/ + + #ifndef MAIN_H #define MAIN_H

diff --git a/src/managed.c b/src/managed.c index 99f8290..71658dc 100644 --- a/src/managed.c +++ b/src/managed.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file managed.c + * \headerfile managed.h + * \brief Implements the 'managed proxy' mode of obfsproxy. + **/ + #include "util.h"

#define MANAGED_PRIVATE diff --git a/src/managed.h b/src/managed.h index 2b14c2b..34382f5 100644 --- a/src/managed.h +++ b/src/managed.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file managed.h + * \brief Headers for managed.c. + **/ + #ifndef MANAGED_H #define MANAGED_H

diff --git a/src/network.c b/src/network.c index a1fbe41..5c3cedf 100644 --- a/src/network.c +++ b/src/network.c @@ -2,6 +2,14 @@ See LICENSE for other credits and copying information */

+/** + * \file network.c + * \headerfile network.h + * \brief Networking side of obfspoxy. Creates listeners, accepts + * connections, reads/writes data, and calls transport callbacks when + * applicable. + **/ + #include "util.h"

#define NETWORK_PRIVATE diff --git a/src/network.h b/src/network.h index 97e3d8c..825a91e 100644 --- a/src/network.h +++ b/src/network.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file network.h + * \brief Headers for network.c. + **/ + #ifndef NETWORK_H #define NETWORK_H

diff --git a/src/obfs_main.c b/src/obfs_main.c index c891e05..f787d69 100644 --- a/src/obfs_main.c +++ b/src/obfs_main.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file obfs_main.c + * \brief Real entry point of obfsproxy. Immediately calls + * main.c:obfs_main(). + **/ + int obfs_main(int argc, char *argv[]);

/** diff --git a/src/protocol.c b/src/protocol.c index 81fd454..4abff90 100644 --- a/src/protocol.c +++ b/src/protocol.c @@ -2,6 +2,15 @@ See LICENSE for other credits and copying information */

+/** + * \file protocol.c + * \headerfile protocol.h + * \brief Pluggable transports-related functions. Acts as a wrapper on + * top of transport callbacks and transport-specific option parsing. + * + * 'Protocol' is a synonym to 'pluggable transport' in obfsproxy code. + **/ + #include "util.h" #include "network.h" #include "protocol.h" diff --git a/src/protocol.h b/src/protocol.h index d360594..2dcc535 100644 --- a/src/protocol.h +++ b/src/protocol.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file protocol.h + * \brief Headers for protocol.c. + **/ + #ifndef PROTOCOL_H #define PROTOCOL_H

diff --git a/src/protocols/dummy.c b/src/protocols/dummy.c index 21fd3ca..f27f48b 100644 --- a/src/protocols/dummy.c +++ b/src/protocols/dummy.c @@ -2,6 +2,13 @@ See LICENSE for other credits and copying information */

+/** + * \file dummy.c + * \headerfile dummy.h + * \brief Implements the 'dummy' pluggable transport. A testing-only + * pluggable transport that leaves traffic intact + **/ + #include "util.h"

#define PROTOCOL_DUMMY_PRIVATE diff --git a/src/protocols/dummy.h b/src/protocols/dummy.h index 3dc1995..150b3ff 100644 --- a/src/protocols/dummy.h +++ b/src/protocols/dummy.h @@ -1,6 +1,12 @@ /* Copyright 2011 Nick Mathewson, George Kadianakis See LICENSE for other credits and copying information */ + +/** + * \file dummy.h + * \brief Headers for dummy.c. + **/ + #ifndef PROTOCOL_DUMMY_H #define PROTOCOL_DUMMY_H

diff --git a/src/protocols/obfs2.c b/src/protocols/obfs2.c index 6e241c3..de26858 100644 --- a/src/protocols/obfs2.c +++ b/src/protocols/obfs2.c @@ -2,6 +2,13 @@ See LICENSE for other credits and copying information */

+/** + * \file obfs2.c + * \headerfile obfs2.h + * \brief Implements the 'obfs2' pluggable transport. + **/ + + #include "util.h"

#define PROTOCOL_OBFS2_PRIVATE diff --git a/src/protocols/obfs2.h b/src/protocols/obfs2.h index fb07407..6030c79 100644 --- a/src/protocols/obfs2.h +++ b/src/protocols/obfs2.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file obfs2.h + * \brief Headers for obfs2.c. + **/ + #ifndef PROTOCOL_OBFS2_H #define PROTOCOL_OBFS2_H

diff --git a/src/sha256.c b/src/sha256.c index 8d835d4..349cdeb 100644 --- a/src/sha256.c +++ b/src/sha256.c @@ -1,8 +1,15 @@ /* Copyright (c) 2009-2011, The Tor Project, Inc. */ /* See the LICENSE file for licensing information */ -/* This SHA256 implementation is adapted from the public domain one in - LibTomCrypt, version 1.6. Tor uses it on platforms where OpenSSL doesn't - have a SHA256. */ + +/** + * \file sha256.c + * \headerfile sha256.h + * \brief SHA256 implementation by Tom St Denis. + * + * This SHA256 implementation is adapted from the public domain one in + * LibTomCrypt, version 1.6. Tor uses it on platforms where OpenSSL + * doesn't have a SHA256. + **/

#include "util.h"

diff --git a/src/sha256.h b/src/sha256.h index 6afdbfe..033f00d 100644 --- a/src/sha256.h +++ b/src/sha256.h @@ -1,4 +1,10 @@ -/* Header file for the fallback (libtomcrypt) implementation of SHA256. */ +/* See the LICENSE file for licensing information */ + +/** + * \file sha256.h + * \brief Headers for sha256.c. + **/ + #ifndef SHA256_H #define SHA256_H

diff --git a/src/socks.c b/src/socks.c index 46bc5d5..51c6dff 100644 --- a/src/socks.c +++ b/src/socks.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file socks.c + * \headerfile socks.h + * \brief SOCKS{5,4,4a} server. + **/ + #include "util.h"

#define SOCKS_PRIVATE diff --git a/src/socks.h b/src/socks.h index a06a11e..4e0bdfa 100644 --- a/src/socks.h +++ b/src/socks.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file socks.h + * \brief Headers for socks.c. + **/ + #ifndef SOCKS_H #define SOCKS_H

diff --git a/src/test/tester.py.in b/src/test/tester.py.in index 4b93784..ea46d1f 100644 --- a/src/test/tester.py.in +++ b/src/test/tester.py.in @@ -1,11 +1,13 @@ #! @PYTHON@

-# Integration tests for obfsproxy. -# -# The obfsproxy binary is assumed to exist in the current working -# directory, and you need to have Python 2.6 or better (but not 3). -# You need to be able to make connections to arbitrary high-numbered -# TCP ports on the loopback interface. +"""@package tester.py.in +Integration tests for obfsproxy. + +The obfsproxy binary is assumed to exist in the current working +directory, and you need to have Python 2.6 or better (but not 3). +You need to be able to make connections to arbitrary high-numbered +TCP ports on the loopback interface. +"""

import difflib import errno diff --git a/src/util.c b/src/util.c index f56ba58..db0dc77 100644 --- a/src/util.c +++ b/src/util.c @@ -2,6 +2,12 @@ See LICENSE for other credits and copying information */

+/** + * \file util.c + * \headerfile util.h + * \brief Utility functions. + **/ + #include "util.h"

#include <errno.h> diff --git a/src/util.h b/src/util.h index 2b37c48..8a7585b 100644 --- a/src/util.h +++ b/src/util.h @@ -2,6 +2,11 @@ See LICENSE for other credits and copying information */

+/** + * \file util.h + * \brief Headers for util.c. + **/ + #ifndef UTIL_H #define UTIL_H