r11629@catbus: nickm | 2007-02-02 15:06:17 -0500

 Removing the last DOCDOC comment hurt so much that I had to use Doxygen to identify undocumented macros and comments, and add 150 more DOCDOCs to point out where they were.  Oops.  Hey, kids!  Fixing some of these could be your first Tor patch!


svn:r9477

12 files changed, 53 insertions, 14 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 9c9da66d6b..4d37363a91 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -107,17 +107,20 @@ const char compat_c_id[] =
 #include "strlcat.c"
 #endif
 
-/* used by inet_addr, not defined on solaris anywhere!? */
 #ifndef INADDR_NONE
+/* This is used by inet_addr, but apparently Solaris doesn't define it
+ * anyplace. */
 #define INADDR_NONE ((unsigned long) -1)
 #endif
 
 #ifdef HAVE_SYS_MMAN_H
+/** DOCDOC */
 typedef struct tor_mmap_impl_t {
   tor_mmap_t base;
   size_t mapping_size; /**< Size of the actual mapping. (This is this file
                         * size, rounded up to the nearest page.) */
 } tor_mmap_impl_t;
+/** DOCDOC */
 tor_mmap_t *
 tor_mmap_file(const char *filename)
 {
@@ -165,6 +168,7 @@ tor_mmap_file(const char *filename)
 
   return &(res->base);
 }
+/** DOCDOC */
 void
 tor_munmap_file(tor_mmap_t *handle)
 {
@@ -174,6 +178,7 @@ tor_munmap_file(tor_mmap_t *handle)
   tor_free(h);
 }
 #elif defined(MS_WINDOWS)
+/** DOCDOC */
 typedef struct win_mmap_t {
   tor_mmap_t base;
   HANDLE file_handle;
@@ -966,6 +971,7 @@ typedef struct tor_pthread_data_t {
   void (*func)(void *);
   void *data;
 } tor_pthread_data_t;
+/** DOCDOC */
 static void *
 tor_pthread_helper_fn(void *_data)
 {
@@ -1092,6 +1098,8 @@ tor_gettimeofday(struct timeval *timeval)
 }
 
 #if defined(TOR_IS_MULTITHREADED) && !defined(MS_WINDOWS)
+/** Defined iff we need to add locks when defining fake versions of reentrant
+ * versions of time-related functions. */
 #define TIME_FNS_NEED_LOCKS
 #endif
 
@@ -1206,6 +1214,7 @@ tor_get_thread_id(void)
 struct tor_mutex_t {
   pthread_mutex_t mutex;
 };
+/** DOCDOC */
 tor_mutex_t *
 tor_mutex_new(void)
 {
@@ -1213,18 +1222,21 @@ tor_mutex_new(void)
   pthread_mutex_init(&mutex->mutex, NULL);
   return mutex;
 }
+/** DOCDOC */
 void
 tor_mutex_acquire(tor_mutex_t *m)
 {
   tor_assert(m);
   pthread_mutex_lock(&m->mutex);
 }
+/** DOCDOC */
 void
 tor_mutex_release(tor_mutex_t *m)
 {
   tor_assert(m);
   pthread_mutex_unlock(&m->mutex);
 }
+/** DOCDOC */
 void
 tor_mutex_free(tor_mutex_t *m)
 {
@@ -1232,6 +1244,7 @@ tor_mutex_free(tor_mutex_t *m)
   pthread_mutex_destroy(&m->mutex);
   tor_free(m);
 }
+/** DOCDOC */
 unsigned long
 tor_get_thread_id(void)
 {
diff --git a/src/common/container.c b/src/common/container.c
index 659e1346d1..efbadc6d2b 100644
--- a/src/common/container.c
+++ b/src/common/container.c
@@ -28,8 +28,7 @@ const char container_c_id[] =
 
 #include "ht.h"
 
-/* All newly allocated smartlists have this capacity.
- */
+/** All newly allocated smartlists have this capacity. */
 #define SMARTLIST_DEFAULT_CAPACITY 32
 
 /** Allocate and return an empty smartlist.
diff --git a/src/common/container.h b/src/common/container.h
index a6b7b56adb..8fbc863cbb 100644
--- a/src/common/container.h
+++ b/src/common/container.h
@@ -11,7 +11,12 @@
 #include "compat.h"
 #include "util.h"
 
-/** A resizeable list of pointers, with associated helpful functionality. */
+/** A resizeable list of pointers, with associated helpful functionality.
+ *
+ * The members of this struct are exposed only so that macros and inlines can
+ * use them; all access to smartlist internals should go throuch the functions
+ * and macros defined here.
+ **/
 typedef struct smartlist_t {
   /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
    * before it needs to be resized.  Only the first <b>num_used</b> (\<=
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 00f3cf4600..0af144d23f 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -550,7 +550,7 @@ crypto_pk_read_public_key_from_string(crypto_pk_env_t *env, const char *src,
   return 0;
 }
 
-/* Write the private key from 'env' into the file named by 'fname',
+/** Write the private key from 'env' into the file named by 'fname',
  * PEM-encoded.  Return 0 on success, -1 on failure.
  */
 int
diff --git a/src/common/crypto.h b/src/common/crypto.h
index 375e2c5500..f09936ef92 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -160,12 +160,14 @@ void *smartlist_choose(const struct smartlist_t *sl);
 
 int base64_encode(char *dest, size_t destlen, const char *src, size_t srclen);
 int base64_decode(char *dest, size_t destlen, const char *src, size_t srclen);
+/** Characters that can appear (case-insensitively) in a base-32 encoding. */
 #define BASE32_CHARS "abcdefghijklmnopqrstuvwxyz234567"
 void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);
 
 int digest_to_base64(char *d64, const char *digest);
 int digest_from_base64(char *digest, const char *d64);
 
+/** DOCDOC */
 #define S2K_SPECIFIER_LEN 9
 void secret_to_key(char *key_out, size_t key_out_len, const char *secret,
                    size_t secret_len, const char *s2k_specifier);
diff --git a/src/common/log.h b/src/common/log.h
index 8122a94aa6..c6b6a6aa6d 100644
--- a/src/common/log.h
+++ b/src/common/log.h
@@ -90,6 +90,7 @@
 /** Bandwidth accounting. */
 #define LD_ACCT     (1u<<17)
 
+/** DOCDOC */
 typedef void (*log_callback)(int severity, uint32_t domain, const char *msg);
 
 int parse_log_level(const char *level);
diff --git a/src/common/torgzip.c b/src/common/torgzip.c
index badd45be87..ad91649405 100644
--- a/src/common/torgzip.c
+++ b/src/common/torgzip.c
@@ -299,6 +299,7 @@ detect_compression_method(const char *in, size_t in_len)
   }
 }
 
+/** DOCDOC */
 struct tor_zlib_state_t {
   struct z_stream_s stream;
   int compress;
diff --git a/src/common/torgzip.h b/src/common/torgzip.h
index a20106cc35..f8e15d75c0 100644
--- a/src/common/torgzip.h
+++ b/src/common/torgzip.h
@@ -12,6 +12,7 @@
 #define __TORGZIP_H
 #define TORGZIP_H_ID "$Id$"
 
+/** DOCDOC */
 typedef enum {
   NO_METHOD=0, GZIP_METHOD=1, ZLIB_METHOD=2, UNKNOWN_METHOD=3
 } compress_method_t;
@@ -31,6 +32,7 @@ int is_gzip_supported(void);
 
 compress_method_t detect_compression_method(const char *in, size_t in_len);
 
+/** DOCDOC */
 typedef enum {
   TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
 }  tor_zlib_output_t;
diff --git a/src/common/tortls.c b/src/common/tortls.c
index 8238073a39..aab3cc4efd 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -103,6 +103,7 @@ tls_log_errors(int severity, const char *doing)
   }
 }
 
+/** DOCDOC */
 static int
 tor_errno_to_tls_error(int e)
 {
@@ -205,6 +206,7 @@ tor_tls_init(void)
   }
 }
 
+/** DOCDOC */
 void
 tor_tls_free_all(void)
 {
@@ -720,6 +722,7 @@ tor_tls_get_peer_cert_nickname(int severity, tor_tls_t *tls,
   return r;
 }
 
+/** DOCDOC */
 static void
 log_cert_lifetime(X509 *cert, const char *problem)
 {
diff --git a/src/common/tortls.h b/src/common/tortls.h
index 50e798cc22..1fe245aabd 100644
--- a/src/common/tortls.h
+++ b/src/common/tortls.h
@@ -31,7 +31,7 @@ typedef struct tor_tls_t tor_tls_t;
 #define TOR_TLS_WANTWRITE          -1
 #define TOR_TLS_DONE                0
 
-/* Use this macro in a switch statement to catch _any_ TLS error.  That way,
+/** Use this macro in a switch statement to catch _any_ TLS error.  That way,
  * if more errors are added, your switches will still work. */
 #define CASE_TOR_TLS_ERROR_ANY                  \
   case TOR_TLS_ERROR_MISC:                      \
diff --git a/src/common/util.c b/src/common/util.c
index d7027b848c..6ecb901eae 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -125,7 +125,7 @@ _tor_malloc(size_t size DMALLOC_PARAMS)
   return result;
 }
 
-/* Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
+/** Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
  * zero bytes, and return a pointer to the result.  Log and terminate
  * the process on error.  (Same as calloc(size,1), but never returns NULL.)
  */
@@ -361,7 +361,7 @@ tor_strisnonupper(const char *s)
   return 1;
 }
 
-/* Compares the first strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the first strlen(s2) characters of s1 with s2.  Returns as for
  * strcmp.
  */
 int
@@ -371,7 +371,7 @@ strcmpstart(const char *s1, const char *s2)
   return strncmp(s1, s2, n);
 }
 
-/* Compares the first strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the first strlen(s2) characters of s1 with s2.  Returns as for
  * strcasecmp.
  */
 int
@@ -381,7 +381,7 @@ strcasecmpstart(const char *s1, const char *s2)
   return strncasecmp(s1, s2, n);
 }
 
-/* Compares the last strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the last strlen(s2) characters of s1 with s2.  Returns as for
  * strcmp.
  */
 int
@@ -394,7 +394,7 @@ strcmpend(const char *s1, const char *s2)
     return strncmp(s1+(n1-n2), s2, n2);
 }
 
-/* Compares the last strlen(s2) characters of s1 with s2.  Returns as for
+/** Compares the last strlen(s2) characters of s1 with s2.  Returns as for
  * strcasecmp.
  */
 int
@@ -624,7 +624,7 @@ hex_decode_digit(char c)
   }
 }
 
-/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src/b>, decode it
+/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src</b>, decode it
  * and store the result in the <b>destlen</b>-byte buffer at <b>dest</b>.
  * Return 0 on success, -1 on failure. */
 int
@@ -878,7 +878,9 @@ tv_addms(struct timeval *a, long ms)
   a->tv_usec %= 1000000;
 }
 
+/** DOCDOC */
 #define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
+/** DOCDOC */
 static int
 n_leapdays(int y1, int y2)
 {
@@ -1263,7 +1265,7 @@ write_str_to_file(const char *fname, const char *str, int bin)
 }
 
 /** Helper: given a set of flags as passed to open(2), open the file
- * <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</t> to
+ * <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</b> to
  * the file.  Do so as atomically as possible e.g. by opening temp files and
  * renaming. */
 static int
@@ -1320,7 +1322,7 @@ write_chunks_to_file_impl(const char *fname, const smartlist_t *chunks,
   return -1;
 }
 
-/* Given a smartlist of sized_chunk_t, write them atomically to a file
+/** Given a smartlist of sized_chunk_t, write them atomically to a file
  * <b>fname</b>, overwriting or creating the file as necessary. */
 int
 write_chunks_to_file(const char *fname, const smartlist_t *chunks, int bin)
@@ -1962,8 +1964,11 @@ get_interface_address(int severity, uint32_t *addr)
 
 #ifndef MS_WINDOWS
 /* Based on code contributed by christian grothoff */
+/** DOCDOC */
 static int start_daemon_called = 0;
+/** DOCDOC */
 static int finish_daemon_called = 0;
+/** DOCDOC */
 static int daemon_filedes[2];
 /** Start putting the process into daemon mode: fork and drop all resources
  * except standard fds.  The parent process never returns, but stays around
diff --git a/src/common/util.h b/src/common/util.h
index b659e5f04e..868f4cde27 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -39,10 +39,13 @@
 #error "Sorry; we don't support building with NDEBUG."
 #else
 #ifdef __GNUC__
+/** DOCDOC */
 #define PREDICT_FALSE(x) PREDICT((x) == ((typeof(x)) 0), 0)
 #else
 #define PREDICT_FALSE(x) !(x)
 #endif
+
+/** DOCDOC */
 #define tor_assert(expr) do {                                           \
     if (PREDICT_FALSE(expr)) {                                          \
       log(LOG_ERR, LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
@@ -106,6 +109,8 @@ extern int dmalloc_free(const char *file, const int line, void *pnt,
 #endif
 
 /* String manipulation */
+
+/** DOCDOC */
 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
 void tor_strlower(char *s) ATTR_NONNULL((1));
 void tor_strupper(char *s) ATTR_NONNULL((1));
@@ -118,6 +123,7 @@ int strcmpend(const char *s1, const char *s2) ATTR_PURE ATTR_NONNULL((1,2));
 int strcasecmpend(const char *s1, const char *s2)
   ATTR_PURE ATTR_NONNULL((1,2));
 int tor_strstrip(char *s, const char *strip) ATTR_NONNULL((1,2));
+/** DOCDOC */
 typedef enum {
   ALWAYS_TERMINATE, NEVER_TERMINATE, TERMINATE_IF_EVEN
 } part_finish_rule_t;
@@ -163,9 +169,11 @@ int parse_iso_time(const char *buf, time_t *t);
 int write_all(int fd, const char *buf, size_t count, int isSocket);
 int read_all(int fd, char *buf, size_t count, int isSocket);
 
+/** DOCDOC */
 typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR} file_status_t;
 file_status_t file_status(const char *filename);
 
+/** DOCDOC */
 typedef enum { CPD_NONE, CPD_CREATE, CPD_CHECK } cpd_check_t;
 int check_private_dir(const char *dirname, cpd_check_t check);
 int write_str_to_file(const char *fname, const char *str, int bin);