Commit 173b18c7 authored by Nick Mathewson's avatar Nick Mathewson 🦀
Browse files

Add about 60 more DOCDOC comments to 0.2.3 

Also, try to resolve some doxygen issues.  First, define a magic
"This is doxygen!" macro so that we take the correct branch in
various #if/#else/#endifs in order to get the right documentation.
Second, add in a few grouping @{ and @} entries in order to get some
variables and fields to get grouped together.
parent b353cd7e

src/common/compat.c

+13 −4
Original line number Diff line number Diff line
@@ -156,7 +156,7 @@ tor_fopen_cloexec(const char *path, const char *mode) 
  return result;

}



#ifdef HAVE_SYS_MMAN_H

#if defined(HAVE_SYS_MMAN_H) || defined(RUNNING_DOXYGEN)

/** Try to create a memory mapping for <b>filename</b> and return it.  On

 * failure, return NULL.  Sets errno properly, using ERANGE to mean

 * "empty file". */
@@ -501,10 +501,13 @@ tor_memmem(const void *_haystack, size_t hlen, 
#endif

}



/* Tables to implement ctypes-replacement TOR_IS*() functions.  Each table

/**

 * Tables to implement ctypes-replacement TOR_IS*() functions.  Each table

 * has 256 bits to look up whether a character is in some set or not.  This

 * fails on non-ASCII platforms, but it is hard to find a platform whose

 * character set is not a superset of ASCII nowadays. */



/**@{*/

const uint32_t TOR_ISALPHA_TABLE[8] =

  { 0, 0, 0x7fffffe, 0x7fffffe, 0, 0, 0, 0 };

const uint32_t TOR_ISALNUM_TABLE[8] =
@@ -517,8 +520,10 @@ const uint32_t TOR_ISPRINT_TABLE[8] = 
  { 0, 0xffffffff, 0xffffffff, 0x7fffffff, 0, 0, 0, 0x0 };

const uint32_t TOR_ISUPPER_TABLE[8] = { 0, 0, 0x7fffffe, 0, 0, 0, 0, 0 };

const uint32_t TOR_ISLOWER_TABLE[8] = { 0, 0, 0, 0x7fffffe, 0, 0, 0, 0 };

/* Upper-casing and lowercasing tables to map characters to upper/lowercase

 * equivalents. */



/** Upper-casing and lowercasing tables to map characters to upper/lowercase

 * equivalents.  Used by tor_toupper() and tor_tolower(). */

/**@{*/

const char TOR_TOUPPER_TABLE[256] = {

  0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,

  16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,
@@ -555,6 +560,7 @@ const char TOR_TOLOWER_TABLE[256] = { 
  224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,

  240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,

};

/**@}*/



/** Helper for tor_strtok_r_impl: Advances cp past all characters in

 * <b>sep</b>, and returns its new value. */
@@ -1779,9 +1785,11 @@ make_path_absolute(char *fname) 
#ifndef HAVE__NSGETENVIRON

#ifndef HAVE_EXTERN_ENVIRON_DECLARED

/* Some platforms declare environ under some circumstances, others don't. */

#ifndef RUNNING_DOXYGEN

extern char **environ;

#endif

#endif

#endif



/** Return the current environment. This is a portable replacement for

 * 'environ'. */
@@ -2356,6 +2364,7 @@ tor_gettimeofday(struct timeval *timeval) 
#define TIME_FNS_NEED_LOCKS

#endif



/* DOCDOC correct_tm */

static struct tm *

correct_tm(int islocal, const time_t *timep, struct tm *resultbuf,

           struct tm *r)

src/common/compat_libevent.c

+3 −4
Original line number Diff line number Diff line
@@ -6,9 +6,8 @@ 
 * \brief Wrappers to handle porting between different versions of libevent.

 *

 * In an ideal world, we'd just use Libevent 2.0 from now on.  But as of June

 * 2009, Libevent 2.0 is still in alpha, and we will have old versions of

 * Libevent for the forseeable future.

 **/

 * 2012, Libevent 1.4 is still all over, and some poor souls are stuck on

 * Libevent 1.3e. */



#include "orconfig.h"

#include "compat.h"
@@ -57,7 +56,7 @@ typedef uint32_t le_version_t; 


static le_version_t tor_get_libevent_version(const char **v_out);



#ifdef HAVE_EVENT_SET_LOG_CALLBACK

#if defined(HAVE_EVENT_SET_LOG_CALLBACK) || defined(RUNNING_DOXYGEN)

/** A string which, if it appears in a libevent log, should be ignored. */

static const char *suppress_msg = NULL;

/** Callback function passed to event_set_log() so we can intercept

src/common/compat_libevent.h

+1 −0
Original line number Diff line number Diff line
@@ -59,6 +59,7 @@ struct timeval; 
int tor_event_base_loopexit(struct event_base *base, struct timeval *tv);

#endif



/* DOCDOC tor_libevent_cfg */

typedef struct tor_libevent_cfg {

  int disable_iocp;

  int num_cpus;

src/common/crypto.c

+3 −1
Original line number Diff line number Diff line
@@ -69,7 +69,7 @@ 
/** Longest recognized */

#define MAX_DNS_LABEL_SIZE 63



#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8)

#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8) && !defined(RUNNING_DOXYGEN)

/** @{ */

/** On OpenSSL versions before 0.9.8, there is no working SHA256

 * implementation, so we use Tom St Denis's nice speedy one, slightly adapted
@@ -404,6 +404,8 @@ crypto_cipher_new_with_iv(const char *key, const char *iv) 
  return env;

}



/** Return a new crypto_cipher_t with the provided <b>key</b> and an IV of all

 * zero bytes.  */

crypto_cipher_t *

crypto_cipher_new(const char *key)

{

src/common/log.c

+1 −0
Original line number Diff line number Diff line
@@ -97,6 +97,7 @@ should_log_function_name(log_domain_mask_t domain, int severity) 


/** A mutex to guard changes to logfiles and logging. */

static tor_mutex_t log_mutex;

/* DOCDOC log_mutex_initialized */

static int log_mutex_initialized = 0;



/** Linked list of logfile_t. */