Resolve about 24 DOCDOCs

6 files changed, 26 insertions, 12 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 629304377f..87fe84cb4b 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -2364,7 +2364,12 @@ tor_gettimeofday(struct timeval *timeval)
 #define TIME_FNS_NEED_LOCKS
 #endif
 
-/* DOCDOC correct_tm */
+/** Helper: Deal with confused or out-of-bounds values from localtime_r and
+ * friends.  (On some platforms, they can give out-of-bounds values or can
+ * return NULL.)  If <b>islocal</b>, this is a localtime result; otherwise
+ * it's from gmtime.  The function returned <b>r</b>, when given <b>timep</b>
+ * as its input. If we need to store new results, store them in
+ * <b>resultbuf</b>. */
 static struct tm *
 correct_tm(int islocal, const time_t *timep, struct tm *resultbuf,
            struct tm *r)
diff --git a/src/common/compat_libevent.h b/src/common/compat_libevent.h
index af819dbc97..224c76fda7 100644
--- a/src/common/compat_libevent.h
+++ b/src/common/compat_libevent.h
@@ -59,10 +59,15 @@ struct timeval;
 int tor_event_base_loopexit(struct event_base *base, struct timeval *tv);
 #endif
 
-/* DOCDOC tor_libevent_cfg */
+/** Defines a configuration for using libevent with Tor: passed as an argument
+ * to tor_libevent_initialize() to describe how we want to set up. */
 typedef struct tor_libevent_cfg {
+  /** Flag: if true, disable IOCP (assuming that it could be enabled). */
   int disable_iocp;
+  /** How many CPUs should we use (relevant only with IOCP). */
   int num_cpus;
+  /** How many milliseconds should we allow between updating bandwidth limits?
+   * (relevant only with bufferevents). */
   int msec_per_tick;
 } tor_libevent_cfg;
 
diff --git a/src/common/log.c b/src/common/log.c
index 37c7a148f0..5966e44459 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -97,7 +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 */
+/** True iff we have initialized log_mutex */
 static int log_mutex_initialized = 0;
 
 /** Linked list of logfile_t. */
diff --git a/src/common/tortls.c b/src/common/tortls.c
index 634589b1cc..a62c2e6a8c 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -223,10 +223,12 @@ static int check_cert_lifetime_internal(int severity, const X509 *cert,
                                    int past_tolerance, int future_tolerance);
 
 /** Global TLS contexts. We keep them here because nobody else needs
- * to touch them. */
+ * to touch them.
+ *
+ * @{ */
 static tor_tls_context_t *server_tls_context = NULL;
-/* DOCDOC client_tls_context */
 static tor_tls_context_t *client_tls_context = NULL;
+/**@}*/
 
 /** True iff tor_tls_init() has been called. */
 static int tls_library_is_initialized = 0;
@@ -269,7 +271,9 @@ tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz)
   tor_snprintf(buf, sz, "%s%s", ssl_state, tortls_state);
 }
 
-/* DOCDOC tor_tls_log_one_error */
+/** Log a single error <b>err</b> as returned by ERR_get_error(), which was
+ * received while performing an operation <b>doing</b> on <b>tls</b>.  Log
+ * the message at <b>severity</b>, in log domain <b>domain</b>. */
 void
 tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
                   int severity, int domain, const char *doing)
@@ -314,8 +318,8 @@ tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
   }
 }
 
-/** Log all pending tls errors at level <b>severity</b>.  Use
- * <b>doing</b> to describe our current activities.
+/** Log all pending tls errors at level <b>severity</b> in log domain
+ * <b>domain</b>.  Use <b>doing</b> to describe our current activities.
  */
 static void
 tls_log_errors(tor_tls_t *tls, int severity, int domain, const char *doing)
@@ -1344,7 +1348,7 @@ tor_tls_client_is_using_v2_ciphers(const SSL *ssl, const char *address)
   return 1;
 }
 
-/* DOCDOC tor_tls_debug_state_callback */
+/** Invoked when a TLS state changes: log the change at severity 'debug' */
 static void
 tor_tls_debug_state_callback(const SSL *ssl, int type, int val)
 {
@@ -1624,7 +1628,7 @@ tor_tls_block_renegotiation(tor_tls_t *tls)
   tls->ssl->s3->flags &= ~SSL3_FLAGS_ALLOW_UNSAFE_LEGACY_RENEGOTIATION;
 }
 
-/* DOCDOC tor_tls_assert_renegotiation_unblocked */
+/** Assert that the flags that allow legacy renegotiation are still set */
 void
 tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls)
 {
diff --git a/src/common/util.h b/src/common/util.h
index cbc0fb2d2e..c9754418a0 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -72,7 +72,6 @@
 /* Memory management */
 void *_tor_malloc(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_malloc_zero(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
-/* DOCDOC _tor_malloc_roundup */
 void *_tor_malloc_roundup(size_t *size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_calloc(size_t nmemb, size_t size DMALLOC_PARAMS) ATTR_MALLOC;
 void *_tor_realloc(void *ptr, size_t size DMALLOC_PARAMS);
diff --git a/src/common/util_codedigest.c b/src/common/util_codedigest.c
index ef7095418b..7384f7dc1a 100644
--- a/src/common/util_codedigest.c
+++ b/src/common/util_codedigest.c
@@ -1,7 +1,8 @@
 
 #include "util.h"
 
-/** DOCDOC */
+/** Return a string describing the digest of the source files in src/common/
+ */
 const char *
 libor_get_digests(void)
 {