[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