Doxygen documentation for about 100 things that didn't have any

About 860 doxygen-less things remain in 0.2.2

1 files changed, 17 insertions, 7 deletions

diff --git a/src/common/compat.h b/src/common/compat.h
index ee20e716c0..35829e18b4 100644
--- a/src/common/compat.h
+++ b/src/common/compat.h
@@ -312,6 +312,7 @@ const char *tor_fix_source_file(const char *fname);
 
 /* ===== Time compatibility */
 #if !defined(HAVE_GETTIMEOFDAY) && !defined(HAVE_STRUCT_TIMEVAL_TV_SEC)
+/** Implementation of timeval for platforms that don't have it. */
 struct timeval {
   time_t tv_sec;
   unsigned int tv_usec;
@@ -364,9 +365,9 @@ int get_n_open_sockets(void);
 #define tor_socket_send(s, buf, len, flags) send(s, buf, len, flags)
 #define tor_socket_recv(s, buf, len, flags) recv(s, buf, len, flags)
 
-/* Define struct in6_addr on platforms that do not have it.  Generally,
- * these platforms are ones without IPv6 support, but we want to have
- * a working in6_addr there anyway, so we can use it to parse IPv6
+/** Implementatino of struct in6_addr for platforms that do not have it.
+ * Generally, these platforms are ones without IPv6 support, but we want to
+ * have a working in6_addr there anyway, so we can use it to parse IPv6
  * addresses. */
 #if !defined(HAVE_STRUCT_IN6_ADDR)
 struct in6_addr
@@ -382,9 +383,10 @@ struct in6_addr
 };
 #endif
 
+/** @{ */
+/** Many BSD variants seem not to define these. */
 #if defined(__APPLE__) || defined(__darwin__) || defined(__FreeBSD__) \
     || defined(__NetBSD__) || defined(__OpenBSD__)
-/* Many BSD variants seem not to define these. */
 #ifndef s6_addr16
 #define s6_addr16 __u6_addr.__u6_addr16
 #endif
@@ -392,12 +394,15 @@ struct in6_addr
 #define s6_addr32 __u6_addr.__u6_addr32
 #endif
 #endif
+/** @} */
 
 #ifndef HAVE_SA_FAMILY_T
 typedef uint16_t sa_family_t;
 #endif
 
-/* Apparently, MS and Solaris don't define s6_addr16 or s6_addr32. */
+/** @{ */
+/** Apparently, MS and Solaris don't define s6_addr16 or s6_addr32; these
+ * macros get you a pointer to s6_addr32 or local equivalent. */
 #ifdef HAVE_STRUCT_IN6_ADDR_S6_ADDR32
 #define S6_ADDR32(x) ((uint32_t*)(x).s6_addr32)
 #else
@@ -408,9 +413,10 @@ typedef uint16_t sa_family_t;
 #else
 #define S6_ADDR16(x) ((uint16_t*)((char*)&(x).s6_addr))
 #endif
+/** @} */
 
-/* Define struct sockaddr_in6 on platforms that do not have it. See notes
- * on struct in6_addr. */
+/** Implementation of struct sockaddr_in6 on platforms that do not have
+ * it. See notes on struct in6_addr. */
 #if !defined(HAVE_STRUCT_SOCKADDR_IN6)
 struct sockaddr_in6 {
   sa_family_t sin6_family;
@@ -534,10 +540,14 @@ void spawn_exit(void) ATTR_NORETURN;
 /** A generic lock structure for multithreaded builds. */
 typedef struct tor_mutex_t {
 #if defined(USE_WIN32_THREADS)
+  /** Windows-only: on windows, we implement locks with CRITICAL_SECTIONS. */
   CRITICAL_SECTION mutex;
 #elif defined(USE_PTHREADS)
+  /** Pthreads-only: with pthreads, we implement locks with
+   * pthread_mutex_t. */
   pthread_mutex_t mutex;
 #else
+  /** No-threads only: Dummy variable so that tor_mutex_t takes up space. */
   int _unused;
 #endif
 } tor_mutex_t;