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

nickm at torproject.org nickm at torproject.org
Mon Dec 12 15:49:48 UTC 2011


commit 6016f54a961d51fe8a2fc2bbee18d41d0127d092
Author: George Kadianakis <desnacked at 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
 





More information about the tor-commits mailing list