Commit fixes for several pending tor core tasks: document all DOCDOCed functions; time out uncontrolled unattached streams; feed reasons to SOCKS5 (refactoring connection_ap_handshake_socks_reply in the process); change DirFetchPeriod/StatusFetchPeriod to have a special "Be smart" value.

svn:r3769

2 files changed, 21 insertions, 4 deletions

diff --git a/src/common/log.c b/src/common/log.c
index 5d8e64f021..c134fe4ee0 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -55,6 +55,9 @@ static void delete_log(logfile_t *victim);
 static void close_log(logfile_t *victim);
 static int reset_log(logfile_t *lf);
 
+/** Helper: Write the standard prefix for log lines to a
+ * <b>buf_len</b> character buffer in <b>buf</b>.
+ */
 static INLINE size_t
 _log_prefix(char *buf, size_t buf_len, int severity)
 {
@@ -290,7 +293,8 @@ static void delete_log(logfile_t *victim) {
   tor_free(victim);
 }
 
-/** DOCDOC */
+/** Helper: release system resources (but not memory) held by a single
+ * logfile_t. */
 static void close_log(logfile_t *victim)
 {
   if (victim->needs_close && victim->file) {
@@ -304,7 +308,9 @@ static void close_log(logfile_t *victim)
   }
 }
 
-/** DOCDOC */
+/** Helper: reset a single logfile_t.  For a file log, this involves
+ * closing and reopening the log, and maybe writing the version.  For
+ * other log types, do nothing. */
 static int reset_log(logfile_t *lf)
 {
   if (lf->needs_close) {
@@ -342,6 +348,11 @@ void add_temp_log(void)
   logfiles->is_temporary = 1;
 }
 
+/**
+ * Add a log handler to send messages of severity between
+ * <b>logLevelmin</b> and <b>logLevelMax</b> to the function
+ * <b>cb</b>.
+ */
 int add_callback_log(int loglevelMin, int loglevelMax, log_callback cb)
 {
   logfile_t *lf;
@@ -437,11 +448,13 @@ int parse_log_level(const char *level) {
   return -1;
 }
 
+/** Return the string equivalent of a given log level. */
 const char *log_level_to_string(int level)
 {
   return sev_to_string(level);
 }
 
+/** Return the least severe log level that any current log is interested in. */
 int get_min_log_level(void)
 {
   logfile_t *lf;
diff --git a/src/common/util.c b/src/common/util.c
index 7ff0869c58..efc25cf5ba 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -1288,6 +1288,10 @@ parse_addr_and_port_range(const char *s, uint32_t *addr_out,
   return -1;
 }
 
+/** Given an IPv4 address <b>in</b> (in network order, as usual),
+ * write it as a string into the <b>buf_len</b>-byte buffer in
+ * <b>buf</b>.
+ */
 int
 tor_inet_ntoa(struct in_addr *in, char *buf, size_t buf_len)
 {
@@ -1299,7 +1303,8 @@ tor_inet_ntoa(struct in_addr *in, char *buf, size_t buf_len)
                       (int)(uint8_t)((a    )&0xff));
 }
 
-/* DOCDOC */
+/* Return true iff <b>name</b> looks like it might be a hostname or IP
+ * address of some kind. */
 int
 is_plausible_address(const char *name)
 {
@@ -1437,4 +1442,3 @@ void write_pidfile(char *filename) {
   }
 #endif
 }
-