3 files changed, 29 insertions, 11 deletions
diff --git a/src/common/compat.c b/src/common/compat.c
index eee9b87b09..710854b1f3 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -1023,9 +1023,12 @@ tor_lookup_hostname(const char *name, uint32_t *addr)
 }
 
 /** 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)
diff --git a/src/common/container.c b/src/common/container.c
index 4cac686147..c31a4d2713 100644
--- a/src/common/container.c
+++ b/src/common/container.c
@@ -196,7 +196,8 @@ smartlist_string_isin(const smartlist_t *sl, const char *element)
   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)
 {
diff --git a/src/common/util.c b/src/common/util.c
index a2ac9b934e..991cda1a97 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -2170,9 +2170,14 @@ parse_addr_and_port_range(const char *s, uint32_t *addr_out,
  *  <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,17 +2444,20 @@ tor_addr_copy(tor_addr_t *dest, const tor_addr_t *src)
   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.
- *
- * Different address families (IPv4 vs IPv6) are always considered unequal.
+/** As tor_addr_compare(), but only looks at the first <b>mask</b> bits of
+ * the address.
  *
  * Reduce over-specific masks (>128 for ipv6, >32 for ipv4) to 128 or 32.
  */
@@ -2464,6 +2472,11 @@ tor_addr_compare_masked(const tor_addr_t *addr1, const tor_addr_t *addr2,
 
   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 @@ tor_dup_addr(uint32_t addr)
 }
 
 /** 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)