[or-cvs] Commit fixes for several pending tor core tasks: document a...

[nickm@xxxxxxxx (Nick Mathewson)]

Update of /home/or/cvsroot/tor/src/common
In directory moria.mit.edu:/tmp/cvs-serv21573/src/common

Modified Files:
	log.c util.c 
Log Message:
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.

Index: log.c
===================================================================
RCS file: /home/or/cvsroot/tor/src/common/log.c,v
retrieving revision 1.86
retrieving revision 1.87
diff -u -d -r1.86 -r1.87
--- log.c	22 Feb 2005 07:03:02 -0000	1.86
+++ log.c	17 Mar 2005 12:38:35 -0000	1.87
@@ -55,6 +55,9 @@
 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 @@
   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 @@
   }
 }
 
-/** 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 @@
   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 @@
   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;

Index: util.c
===================================================================
RCS file: /home/or/cvsroot/tor/src/common/util.c,v
retrieving revision 1.205
retrieving revision 1.206
diff -u -d -r1.205 -r1.206
--- util.c	16 Mar 2005 00:04:59 -0000	1.205
+++ util.c	17 Mar 2005 12:38:35 -0000	1.206
@@ -1288,6 +1288,10 @@
   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 @@
                       (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 @@
   }
 #endif
 }
-