[or-cvs] r10991: Add missing code documentation in src/common (in tor/trunk: . src/common)

[nickm@xxxxxxxx]

Author: nickm
Date: 2007-07-30 13:46:12 -0400 (Mon, 30 Jul 2007)
New Revision: 10991

Modified:
   tor/trunk/
   tor/trunk/src/common/compat.c
   tor/trunk/src/common/container.c
   tor/trunk/src/common/util.c
Log:
 r14015@catbus:  nickm | 2007-07-30 13:18:05 -0400
 Add missing code documentation in src/common



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r14015] on 8246c3cf-6607-4228-993b-4d95d33730f1

Modified: tor/trunk/src/common/compat.c
===================================================================
--- tor/trunk/src/common/compat.c	2007-07-30 14:14:43 UTC (rev 10990)
+++ tor/trunk/src/common/compat.c	2007-07-30 17:46:12 UTC (rev 10991)
@@ -1023,9 +1023,12 @@
 }
 
 /** Similar behavior to Unix gethostbyname: resolve <b>name</b>, and set
- * *<b>addr</b> to the proper IP address and family.
+ * *<b>addr</b> to the proper IP address and family. The <b>family</b>
+ * argument (which must be AF_INET, AF_INET6, or AF_UNSPEC) declares a
+ * <i>preferred</i> family, though another one may be returned if only one
+ * family is implemented for this address.
+ *
  * Return 0 on success, -1 on failure; 1 on transient failure.
- * DOCDOC family argument.
  */
 int
 tor_addr_lookup(const char *name, uint16_t family, tor_addr_t *addr)

Modified: tor/trunk/src/common/container.c
===================================================================
--- tor/trunk/src/common/container.c	2007-07-30 14:14:43 UTC (rev 10990)
+++ tor/trunk/src/common/container.c	2007-07-30 17:46:12 UTC (rev 10991)
@@ -196,7 +196,8 @@
   return 0;
 }
 
-/** DOCDOC */
+/** If <b>element</b> is equal to an element of <b>sl</b>, return that
+ * element's index.  Otherwise, return -1. */
 int
 smartlist_string_pos(const smartlist_t *sl, const char *element)
 {

Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c	2007-07-30 14:14:43 UTC (rev 10990)
+++ tor/trunk/src/common/util.c	2007-07-30 17:46:12 UTC (rev 10991)
@@ -2170,9 +2170,14 @@
  *  <b>addr_out</b>, a mask (if any) in <b>mask_out</b>, and port(s) (if any)
  *  in <b>port_min_out</b> and <b>port_max_out</b>.
  *
- * DOCDOC exact syntax.
+ * The syntax is:
+ *   Address OptMask OptPortRange
+ *   Address ::= IPv4Address / "[" IPv6Address "]" / "*"
+ *   OptMask ::= "/" Integer /
+ *   OptPortRange ::= ":*" / ":" Integer / ":" Integer "-" Integer /
  *
- *  - If mask, minport, or maxport are NULL, avoid storing those elements.
+ *  - If mask, minport, or maxport are NULL, we do not want these
+ *    options to be set; treat them as an error if present.
  *  - If the string has no mask, the mask is set to /32 (IPv4) or /128 (IPv6).
  *  - If the string has one port, it is placed in both min and max port
  *    variables.
@@ -2439,18 +2444,21 @@
   memcpy(dest, src, sizeof(tor_addr_t));
 }
 
-/** DOCDOC */
+/** Given two addresses <b>addr1</b> and <b>addr2</b>, return 0 if the two
+ * addresses are equivalent under the mask mbits, less than 0 if addr1
+ * preceeds addr2, and greater than 0 otherwise.
+ *
+ * Different address families (IPv4 vs IPv6) are always considered unequal.
+ */
 int
 tor_addr_compare(const tor_addr_t *addr1, const tor_addr_t *addr2)
 {
   return tor_addr_compare_masked(addr1, addr2, 128);
 }
 
-/** Given two addresses <b>addr1</b> and <b>addr2</b>, return 0 if the two
- * addresses are equivalent under the mask mbits, or nonzero if not.
+/** As tor_addr_compare(), but only looks at the first <b>mask</b> bits of
+ * the address.
  *
- * Different address families (IPv4 vs IPv6) are always considered unequal.
- *
  * Reduce over-specific masks (>128 for ipv6, >32 for ipv4) to 128 or 32.
  */
 int
@@ -2464,6 +2472,11 @@
 
   tor_assert(addr1 && addr2);
 
+  /* XXXX020 this code doesn't handle mask bits right it's using v4-mapped v6
+   * addresses.  If I ask whether ::ffff:1.2.3.4 and ::ffff:1.2.7.8 are the
+   * same in the first 16 bits, it will say "yes."  That's not so intuitive.
+   */
+
   v_family[0] = IN_FAMILY(addr1);
   v_family[1] = IN_FAMILY(addr2);
 
@@ -2548,7 +2561,8 @@
 }
 
 /** Convert the tor_addr_t *<b>addr</b> into string form and store it in
- * <b>dest</b> (no more than <b>len</b> bytes). DOCDOC return value.
+ * <b>dest</b>, which can hold at least <b>len</b> bytes.  Returns <b>dest</b>
+ * on success, NULL on failure.
  */
 const char *
 tor_addr_to_str(char *dest, const tor_addr_t *addr, int len)