commit 9687efb386141e5fc46ab295b32bf2dff1f9845b Author: Nick Mathewson <nickm@torproject.org> Date: Wed Nov 6 14:40:20 2019 -0500 Add a bunch of doxygen for things in src/lib. --- src/lib/arch/bytes.h | 21 ++++++++++++-- src/lib/ctime/di_ops.c | 3 ++ src/lib/ctime/di_ops.h | 23 +++++++++++++++- src/lib/defs/time.h | 2 +- src/lib/defs/x25519_sizes.h | 8 ++++++ src/lib/fdio/fdio.c | 7 +++-- src/lib/geoip/country.h | 1 + src/lib/geoip/geoip.c | 16 +++++++---- src/lib/geoip/geoip.h | 1 + src/lib/lock/compat_mutex.h | 5 ++++ src/lib/lock/compat_mutex_pthreads.c | 6 ++++ src/lib/memarea/memarea.h | 3 ++ src/lib/pubsub/pubsub_build.h | 5 ++++ src/lib/pubsub/pubsub_check.c | 2 ++ src/lib/pubsub/pubsub_macros.h | 8 +++--- src/lib/subsys/subsys.h | 12 ++++++-- src/lib/testsupport/testsupport.h | 53 ++++++++++++++++++++++++++++++------ src/lib/version/git_revision.c | 6 ++++ src/lib/version/version.c | 4 +++ src/lib/wallclock/approx_time.c | 6 ++++ 20 files changed, 165 insertions(+), 27 deletions(-) diff --git a/src/lib/arch/bytes.h b/src/lib/arch/bytes.h index 4756ca2be..245dc94bb 100644 --- a/src/lib/arch/bytes.h +++ b/src/lib/arch/bytes.h @@ -16,12 +16,17 @@ #include <string.h> #include "lib/cc/torint.h" -/* The uint8 variants are defined to make the code more uniform. */ +/** + * Read an 8-bit from <b>cp</b>. + */ static inline uint8_t get_uint8(const void *cp) { return *(const uint8_t*)(cp); } +/** + * Store an 8-bit value from <b>v</b> to <b>cp</b>. + */ static inline void set_uint8(void *cp, uint8_t v) { @@ -93,7 +98,7 @@ set_uint64(void *cp, uint64_t v) memcpy(cp,&v,8); } -#ifdef WORDS_BIGENDIAN +#if defined(WORDS_BIGENDIAN) static inline uint16_t tor_htons(uint32_t a) { @@ -130,6 +135,9 @@ tor_ntohll(uint64_t a) return a; } #else /* !defined(WORDS_BIGENDIAN) */ +/** + * Convert a 16-bit value from host order to network order (big-endian). + **/ static inline uint16_t tor_htons(uint16_t a) { @@ -139,12 +147,18 @@ tor_htons(uint16_t a) ((a & 0xff00) >> 8); } +/** + * Convert a 16-bit value from network order (big-endian) to host order. + **/ static inline uint16_t tor_ntohs(uint16_t a) { return tor_htons(a); } +/** + * Convert a 32-bit value from host order to network order (big-endian). + **/ static inline uint32_t tor_htonl(uint32_t a) { @@ -156,6 +170,9 @@ tor_htonl(uint32_t a) ((a & 0xff000000) >>24); } +/** + * Convert a 32-bit value from network order (big-endian) to host order. + **/ static inline uint32_t tor_ntohl(uint32_t a) { diff --git a/src/lib/ctime/di_ops.c b/src/lib/ctime/di_ops.c index 89e0837ae..a96a888b0 100644 --- a/src/lib/ctime/di_ops.c +++ b/src/lib/ctime/di_ops.c @@ -145,8 +145,11 @@ tor_memeq(const void *a, const void *b, size_t sz) /* Implement di_digest256_map_t as a linked list of entries. */ struct di_digest256_map_t { + /** Pointer to the next entry in the list. */ struct di_digest256_map_t *next; + /** Key for this entry. */ uint8_t key[32]; + /** Value for this entry. */ void *val; }; diff --git a/src/lib/ctime/di_ops.h b/src/lib/ctime/di_ops.h index 264b56a8c..fea8f93e3 100644 --- a/src/lib/ctime/di_ops.h +++ b/src/lib/ctime/di_ops.h @@ -16,6 +16,8 @@ int tor_memcmp(const void *a, const void *b, size_t sz); int tor_memeq(const void *a, const void *b, size_t sz); +/** Perform a constant-time comparison of the <b>sz</b> bytes at <b>a</b> and + * <b>b</b>, yielding true if they are different, and false otherwise. */ #define tor_memneq(a,b,sz) (!tor_memeq((a),(b),(sz))) /** Alias for the platform's memcmp() function. This function is @@ -24,7 +26,19 @@ int tor_memeq(const void *a, const void *b, size_t sz); * implementation. */ #define fast_memcmp(a,b,c) (memcmp((a),(b),(c))) +/** Alias for the platform's memcmp() function, for use in testing equality. + * + * This function is <em>not</em> data-independent: we define this alias so + * that we can mark cases where we are deliberately using a data-dependent + * memcmp() implementation. + */ #define fast_memeq(a,b,c) (0==memcmp((a),(b),(c))) +/** Alias for the platform's memcmp() function, for use in testing inequality. + * + * This function is <em>not</em> data-independent: we define this alias so + * that we can mark cases where we are deliberately using a data-dependent + * memcmp() implementation. + */ #define fast_memneq(a,b,c) (0!=memcmp((a),(b),(c))) int safe_mem_is_zero(const void *mem, size_t sz); @@ -35,9 +49,17 @@ int safe_mem_is_zero(const void *mem, size_t sz); * * Not efficient for large maps! */ typedef struct di_digest256_map_t di_digest256_map_t; +/** + * Type for a function used to free members of a di_digest256_map_t. + **/ typedef void (*dimap_free_fn)(void *); void dimap_free_(di_digest256_map_t *map, dimap_free_fn free_fn); +/** + * @copydoc dimap_free_ + * + * Additionally, set the pointer <b>map</b> to NULL. + **/ #define dimap_free(map, free_fn) \ do { \ dimap_free_((map), (free_fn)); \ @@ -52,4 +74,3 @@ int select_array_member_cumulative_timei(const uint64_t *entries, uint64_t total, uint64_t rand_val); #endif /* !defined(TOR_DI_OPS_H) */ - diff --git a/src/lib/defs/time.h b/src/lib/defs/time.h index 459afbf42..160970270 100644 --- a/src/lib/defs/time.h +++ b/src/lib/defs/time.h @@ -17,7 +17,7 @@ #define TOR_USEC_PER_SEC (1000000) /** How many nanoseconds per microsecond */ #define TOR_NSEC_PER_USEC (1000) -/* How many nanoseconds per millisecond */ +/** How many nanoseconds per millisecond */ #define TOR_NSEC_PER_MSEC (1000*1000) #endif /* !defined(TOR_TIME_DEFS_H) */ diff --git a/src/lib/defs/x25519_sizes.h b/src/lib/defs/x25519_sizes.h index 6431f0a2d..080bb4282 100644 --- a/src/lib/defs/x25519_sizes.h +++ b/src/lib/defs/x25519_sizes.h @@ -23,14 +23,22 @@ /** Length of the result of a curve25519 handshake. */ #define CURVE25519_OUTPUT_LEN 32 +/** Length of an Ed25519 public key */ #define ED25519_PUBKEY_LEN 32 +/** Length of an Ed25519 secret key */ #define ED25519_SECKEY_LEN 64 +/** Length of the seed that is ordinarily expanded to an Ed25519 secret + * key. */ #define ED25519_SECKEY_SEED_LEN 32 +/** Length of an Ed25519 signature. */ #define ED25519_SIG_LEN 64 +/** Length of a Curve25519 key when encoded in base 64, with padding. */ #define CURVE25519_BASE64_PADDED_LEN 44 +/** Length of a Ed25519 key when encoded in base 64, without padding. */ #define ED25519_BASE64_LEN 43 +/** Length of a Ed25519 signature when encoded in base 64, without padding. */ #define ED25519_SIG_BASE64_LEN 86 #endif /* !defined(TOR_X25519_SIZES_H) */ diff --git a/src/lib/fdio/fdio.c b/src/lib/fdio/fdio.c index 078af6a9b..bfda26a43 100644 --- a/src/lib/fdio/fdio.c +++ b/src/lib/fdio/fdio.c @@ -28,9 +28,10 @@ #include <stdlib.h> #include <stdio.h> -/** @{ */ -/** Some old versions of Unix didn't define constants for these values, +/* Some old versions of Unix didn't define constants for these values, * and instead expect you to say 0, 1, or 2. */ + +/** @cond */ #ifndef SEEK_SET #define SEEK_SET 0 #endif @@ -40,7 +41,7 @@ #ifndef SEEK_END #define SEEK_END 2 #endif -/** @} */ +/** @endcond */ /** Return the position of <b>fd</b> with respect to the start of the file. */ off_t diff --git a/src/lib/geoip/country.h b/src/lib/geoip/country.h index 2bff4f447..e6d7d77e7 100644 --- a/src/lib/geoip/country.h +++ b/src/lib/geoip/country.h @@ -16,6 +16,7 @@ /** A signed integer representing a country code. */ typedef int16_t country_t; +/** Maximum value for country_t. */ #define COUNTRY_MAX INT16_MAX #endif /* !defined(TOR_COUNTRY_H) */ diff --git a/src/lib/geoip/geoip.c b/src/lib/geoip/geoip.c index 70b1c2dc8..2e0be13c0 100644 --- a/src/lib/geoip/geoip.c +++ b/src/lib/geoip/geoip.c @@ -70,12 +70,18 @@ static smartlist_t *geoip_countries = NULL; * The index is encoded in the pointer, and 1 is added so that NULL can mean * not found. */ static strmap_t *country_idxplus1_by_lc_code = NULL; -/** Lists of all known geoip_ipv4_entry_t and geoip_ipv6_entry_t, sorted - * by their respective ip_low. */ -static smartlist_t *geoip_ipv4_entries = NULL, *geoip_ipv6_entries = NULL; - -/** SHA1 digest of the GeoIP files to include in extra-info descriptors. */ +/** List of all known geoip_ipv4_entry_t sorted + * by their respective ip_low values. */ +static smartlist_t *geoip_ipv4_entries = NULL; +/** List of all known geoip_ipv6_entry_t, sorted by their respective + * ip_low values. */ +static smartlist_t *geoip_ipv6_entries = NULL; + +/** SHA1 digest of the IPv4 GeoIP file to include in extra-info + * descriptors. */ static char geoip_digest[DIGEST_LEN]; +/** SHA1 digest of the IPv6 GeoIP file to include in extra-info + * descriptors. */ static char geoip6_digest[DIGEST_LEN]; /** Return a list of geoip_country_t for all known countries. */ diff --git a/src/lib/geoip/geoip.h b/src/lib/geoip/geoip.h index f872ebd25..1407d0a1e 100644 --- a/src/lib/geoip/geoip.h +++ b/src/lib/geoip/geoip.h @@ -31,6 +31,7 @@ int geoip_get_country_by_ipv6(const struct in6_addr *addr); /** A per-country GeoIP record. */ typedef struct geoip_country_t { + /** A nul-terminated two-letter country-code. */ char countrycode[3]; } geoip_country_t; diff --git a/src/lib/lock/compat_mutex.h b/src/lib/lock/compat_mutex.h index e0c3d7cb7..6fd4c1eb0 100644 --- a/src/lib/lock/compat_mutex.h +++ b/src/lib/lock/compat_mutex.h @@ -58,6 +58,11 @@ void tor_mutex_init_nonrecursive(tor_mutex_t *m); void tor_mutex_acquire(tor_mutex_t *m); void tor_mutex_release(tor_mutex_t *m); void tor_mutex_free_(tor_mutex_t *m); +/** + * @copydoc tor_mutex_free_ + * + * Additionally, set the pointer <b>m</b> to NULL. + **/ #define tor_mutex_free(m) FREE_AND_NULL(tor_mutex_t, tor_mutex_free_, (m)) void tor_mutex_uninit(tor_mutex_t *m); diff --git a/src/lib/lock/compat_mutex_pthreads.c b/src/lib/lock/compat_mutex_pthreads.c index f82ad9f0e..a7f5986ec 100644 --- a/src/lib/lock/compat_mutex_pthreads.c +++ b/src/lib/lock/compat_mutex_pthreads.c @@ -17,8 +17,14 @@ * "recursive" mutexes (i.e., once we can re-lock if we're already holding * them.) */ static pthread_mutexattr_t attr_recursive; +/** + * True iff <b>attr_recursive</b> has been initialized. + **/ static int attr_initialized = 0; +/** + * Initialize the locking module, if it is not already initialized. + **/ void tor_locking_init(void) { diff --git a/src/lib/memarea/memarea.h b/src/lib/memarea/memarea.h index 9c23cf62e..dd0ed57fb 100644 --- a/src/lib/memarea/memarea.h +++ b/src/lib/memarea/memarea.h @@ -16,6 +16,9 @@ typedef struct memarea_t memarea_t; memarea_t *memarea_new(void); void memarea_drop_all_(memarea_t *area); +/** @copydoc memarea_drop_all_ + * + * Additionally, set <b>area</b> to NULL. */ #define memarea_drop_all(area) \ do { \ memarea_drop_all_(area); \ diff --git a/src/lib/pubsub/pubsub_build.h b/src/lib/pubsub/pubsub_build.h index 5a0c5f5bd..13ec09c98 100644 --- a/src/lib/pubsub/pubsub_build.h +++ b/src/lib/pubsub/pubsub_build.h @@ -85,6 +85,11 @@ struct dispatch_t *pubsub_builder_finalize(pubsub_builder_t *, **/ void pubsub_items_clear_bindings(pubsub_items_t *items); +/** + * @copydoc pubsub_items_free_ + * + * Additionally, set the pointer <b>cfg</b> to NULL. + **/ #define pubsub_items_free(cfg) \ FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg)) void pubsub_items_free_(pubsub_items_t *cfg); diff --git a/src/lib/pubsub/pubsub_check.c b/src/lib/pubsub/pubsub_check.c index bf1196df2..38723e56e 100644 --- a/src/lib/pubsub/pubsub_check.c +++ b/src/lib/pubsub/pubsub_check.c @@ -9,7 +9,9 @@ * @brief Enforce various requirements on a pubsub_builder. **/ +/** @{ */ #define PUBSUB_PRIVATE +/** @} */ #include "lib/dispatch/dispatch_naming.h" #include "lib/dispatch/msgtypes.h" diff --git a/src/lib/pubsub/pubsub_macros.h b/src/lib/pubsub/pubsub_macros.h index 357e59fd5..5c02fc354 100644 --- a/src/lib/pubsub/pubsub_macros.h +++ b/src/lib/pubsub/pubsub_macros.h @@ -163,7 +163,7 @@ * hookfn with the appropriate arguments. */ -/* Macro to declare common elements shared by DECLARE_MESSAGE and +/** Macro to declare common elements shared by DECLARE_MESSAGE and * DECLARE_MESSAGE_INT. Don't call this directly. * * Note that the "msg_arg_name" string constant is defined in each @@ -288,7 +288,7 @@ ( 0 ? (publish_fn__ ##messagename((msg_arg_type__##messagename)0), 1) \ : 1) -/* +/** * This macro is for internal use. It backs DISPATCH_ADD_PUB*() */ #define DISPATCH_ADD_PUB_(connector, channel, messagename, flags) \ @@ -322,7 +322,7 @@ #define DISPATCH_ADD_PUB_EXCL(connector, channel, messagename) \ DISPATCH_ADD_PUB_(connector, channel, messagename, DISP_FLAG_EXCL) -/* +/** * This macro is for internal use. It backs DISPATCH_ADD_SUB*() */ #define DISPATCH_ADD_SUB_(connector, channel, messagename, flags) \ @@ -334,7 +334,7 @@ (flags), \ __FILE__, \ __LINE__) -/* +/** * Use a given connector and channel name to declare that this subsystem will * receive a given message type. * diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h index 35a30680e..91abdb7d7 100644 --- a/src/lib/subsys/subsys.h +++ b/src/lib/subsys/subsys.h @@ -90,11 +90,19 @@ typedef struct subsys_fns_t { } subsys_fns_t; +/** + * Lowest allowed subsystem level. + **/ #define MIN_SUBSYS_LEVEL -100 +/** + * Highest allowed subsystem level. + **/ #define MAX_SUBSYS_LEVEL 100 -/* All tor "libraries" (in src/libs) should have a subsystem level equal to or - * less than this value. */ +/** + * All tor "libraries" (in src/libs) should have a subsystem level equal to or + * less than this value. + */ #define SUBSYS_LEVEL_LIBS -10 #endif /* !defined(TOR_SUBSYS_T) */ diff --git a/src/lib/testsupport/testsupport.h b/src/lib/testsupport/testsupport.h index 90b7c43b1..833515c32 100644 --- a/src/lib/testsupport/testsupport.h +++ b/src/lib/testsupport/testsupport.h @@ -15,17 +15,42 @@ #ifndef TOR_TESTSUPPORT_H #define TOR_TESTSUPPORT_H -#ifdef TOR_UNIT_TESTS /** The "STATIC" macro marks a function or variable that is static when * building Tor for production, but non-static when building the unit - * tests. */ + * tests. + * + * For example, a function declared as: + * + * STATIC int internal_function(void); + * + * should be only visible for the file on which it is declared, and in the + * unit tests. + */ +#ifdef TOR_UNIT_TESTS #define STATIC -#define EXTERN(type, name) extern type name; #else /* !defined(TOR_UNIT_TESTS) */ #define STATIC static -#define EXTERN(type, name) #endif /* defined(TOR_UNIT_TESTS) */ +/** The "EXTERN" macro is used along with "STATIC" for variables declarations: + * it expands to an extern declaration when Tor building unit tests, and to + * nothing otherwise. + * + * For example, to declare a variable as visible only visible in one + * file and in the unit tests, you would put this in the header: + * + * EXTERN(int, local_variable) + * + * and this in the source: + * + * STATIC int local_variable; + */ +#ifdef TOR_UNIT_TESTS +#define EXTERN(type, name) extern type name; +#else +#define EXTERN(type, name) +#endif + /** Quick and dirty macros to implement test mocking. * * To use them, suppose that you have a function you'd like to mock @@ -70,32 +95,42 @@ * * @{ */ #ifdef TOR_UNIT_TESTS +/** Declare a mocked function. For use in headers. */ #define MOCK_DECL(rv, funcname, arglist) \ rv funcname ##__real arglist; \ extern rv(*funcname) arglist +/** Define the implementation of a mocked function. */ #define MOCK_IMPL(rv, funcname, arglist) \ rv(*funcname) arglist = funcname ##__real; \ rv funcname ##__real arglist +/** As MOCK_DECL(), but allow attributes. */ #define MOCK_DECL_ATTR(rv, funcname, arglist, attr) \ rv funcname ##__real arglist attr; \ extern rv(*funcname) arglist -#define MOCK_IMPL(rv, funcname, arglist) \ - rv(*funcname) arglist = funcname ##__real; \ - rv funcname ##__real arglist +/** + * Replace <b>func</b> (a mockable function) with a replacement function. + * + * Only usable when Tor has been built for unit tests. */ #define MOCK(func, replacement) \ do { \ (func) = (replacement); \ } while (0) +/** Replace <b>func</b> (a mockable function) with its original value. + * + * Only usable when Tor has been built for unit tests. */ #define UNMOCK(func) \ do { \ func = func ##__real; \ } while (0) #else /* !defined(TOR_UNIT_TESTS) */ +/** Declare a mocked function. For use in headers. */ #define MOCK_DECL(rv, funcname, arglist) \ rv funcname arglist -#define MOCK_DECL_ATTR(rv, funcname, arglist, attr) \ +/** As MOCK_DECL(), but allow */ +#define MOCK_DECL_ATTR(rv, funcname, arglist, attr) \ rv funcname arglist attr -#define MOCK_IMPL(rv, funcname, arglist) \ +/** Define the implementation of a mocked function. */ +#define MOCK_IMPL(rv, funcname, arglist) \ rv funcname arglist #endif /* defined(TOR_UNIT_TESTS) */ /** @} */ diff --git a/src/lib/version/git_revision.c b/src/lib/version/git_revision.c index e87620a20..9ee49f0c3 100644 --- a/src/lib/version/git_revision.c +++ b/src/lib/version/git_revision.c @@ -23,6 +23,12 @@ const char tor_git_revision[] = #endif ""; +/** + * String appended to Tor bug messages describing the Tor version. + * + * It has the form "(on Tor 0.4.3.1-alpha)" or + * "(on Tor 0.4.3.1-alpha git-b994397f1af193f8)" + **/ const char tor_bug_suffix[] = " (on Tor " VERSION #ifndef COCCI #ifndef _MSC_VER diff --git a/src/lib/version/version.c b/src/lib/version/version.c index b2f25e97b..b08d566e1 100644 --- a/src/lib/version/version.c +++ b/src/lib/version/version.c @@ -24,6 +24,10 @@ static const char the_short_tor_version[] = #endif ""; +/** + * Longest possible version length. We make this a constant so that we + * can statically allocate the_tor_version. + **/ #define MAX_VERSION_LEN 128 /** The version of this Tor process, possibly including git version */ diff --git a/src/lib/wallclock/approx_time.c b/src/lib/wallclock/approx_time.c index 77eeddaf5..c3cac8b9f 100644 --- a/src/lib/wallclock/approx_time.c +++ b/src/lib/wallclock/approx_time.c @@ -44,6 +44,9 @@ update_approx_time(time_t now) } #endif /* !defined(TIME_IS_FAST) */ +/** + * Initialize the "wallclock" subsystem by setting the current cached time. + **/ static int subsys_wallclock_initialize(void) { @@ -51,6 +54,9 @@ subsys_wallclock_initialize(void) return 0; } +/** + * Subsystem function table describing the "wallclock" subsystem. + **/ const subsys_fns_t sys_wallclock = { .name = "wallclock", .supported = true,