r13050@catbus: nickm | 2007-05-29 13:31:11 -0400

 Resolve all but 3 DOCDOCs.


svn:r10393

4 files changed, 28 insertions, 7 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 852cfffae3..ed06701ab7 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -807,7 +807,14 @@ tor_inet_aton(const char *c, struct in_addr* addr)
 #endif
 }
 
-/** DOCDOC */
+/** Given <b>af</b>==AF_INET and <b>src</b> a struct in_addr, or
+ * <b>af</b>==AF_INET6 and <b>src</b> a struct in6_addr, try to format the
+ * address and store it in the <b>len</b>-byte buffer <b>dst</b>.  Returns
+ * <b>dst</b> on success, NULL on failure.
+ *
+ * (Like inet_ntop(af,src,dst,len), but works on platforms that don't have it:
+ * Tor sometimes needs to format ipv6 addresses even on platforms without ipv6
+ * support.) */
 const char *
 tor_inet_ntop(int af, const void *src, char *dst, size_t len)
 {
@@ -881,7 +888,15 @@ tor_inet_ntop(int af, const void *src, char *dst, size_t len)
 #endif
 }
 
-/** DOCDOC */
+/** Given <b>af</b>==AF_INET or <b>af</b>==AF_INET6, and a string <b>src</b>
+ * encoding an IPv4 address or IPv6 address correspondingly, try to parse the
+ * address and store the result in <b>dst</b> (which must have space for a
+ * struct in_addr or a struct in6_addr, as appropriate).  Return 1 on success,
+ * 0 on a bad parse, and -1 on a bad <b>af</b>.
+ *
+ * (Like inet_pton(af,src,dst) but works on platforms that don't have it: Tor
+ * sometimes needs to format ipv6 addresses even on platforms without ipv6
+ * support.) */
 int
 tor_inet_pton(int af, const char *src, void *dst)
 {
diff --git a/src/common/container.h b/src/common/container.h
index 280c1a8c7e..735965358a 100644
--- a/src/common/container.h
+++ b/src/common/container.h
@@ -78,8 +78,8 @@ extern INLINE void smartlist_set(smartlist_t *sl, int idx, void *val) {
 #define smartlist_set(sl, idx, val) ((sl)->list[idx] = (val))
 #endif
 
-// void smartlist_swap(smartlist_t *sl, int idx1, int idx2);
-/**DOCDOC*/
+/** Exchange the elements at indices <b>idx1</b> and <b>idx2</b> of the
+ * smartlist <b>sl</b>. */
 static INLINE void smartlist_swap(smartlist_t *sl, int idx1, int idx2)
 {
   if (idx1 != idx2) {
diff --git a/src/common/log.c b/src/common/log.c
index 7e83d831a8..ac28830dfa 100644
--- a/src/common/log.c
+++ b/src/common/log.c
@@ -88,10 +88,15 @@ int _log_global_min_severity = LOG_NOTICE;
 static void delete_log(logfile_t *victim);
 static void close_log(logfile_t *victim);
 
-/** DOCDOC */
+/** Name of the application: used to generate the message we write at the
+ * start of each new log. */
 static char *appname = NULL;
 
-/** DOCDOC */
+/** Set the "application name" for the logs to <b>name</b>: we'll use this
+ * name in the message we write when starting up, and at the start of each new
+ * log.
+ *
+ * Tor uses this string to write the version number to the log file. */
 void
 log_set_application_name(const char *name)
 {
diff --git a/src/common/mempool.c b/src/common/mempool.c
index 16a7f1390a..fa5636f88f 100644
--- a/src/common/mempool.c
+++ b/src/common/mempool.c
@@ -498,8 +498,9 @@ mp_pool_assert_ok(mp_pool_t *pool)
 }
 
 #ifdef TOR
+/** Dump information about <b>pool</b>'s memory usage to the Tor log at level
+ * <b>severity</b>. */
 /*FFFF uses Tor logging functions. */
-/**DOCDOC*/
 void
 mp_pool_log_status(mp_pool_t *pool, int severity)
 {