r11639@catbus: nickm | 2007-02-05 13:33:38 -0500

 Add documentation to src/common/*.h; improve documentation for SMARTLIST_FOREACH; remove never-used options and corresponding tests from tor_strpartition.


svn:r9483

8 files changed, 49 insertions, 54 deletions

diff --git a/src/common/container.h b/src/common/container.h
index 8fbc863cb..2756fdeef 100644
--- a/src/common/container.h
+++ b/src/common/container.h
@@ -113,7 +113,12 @@ char *smartlist_join_strings2(smartlist_t *sl, const char *join,
 /** Iterate over the items in a smartlist <b>sl</b>, in order.  For each item,
  * assign it to a new local variable of type <b>type</b> named <b>var</b>, and
  * execute the statement <b>cmd</b>.  Inside the loop, the loop index can
- * be accessed as <b>var</b>_sl_idx.
+ * be accessed as <b>var</b>_sl_idx and the length of the list can be accessed
+ * as <b>var</b>_sl_len.
+ *
+ * NOTE: Do not change the length of the list while the loop is in progress,
+ * unless you adjust the _sl_len variable correspondingly.  See second example
+ * below.
  *
  * Example use:
  * <pre>
@@ -123,7 +128,20 @@ char *smartlist_join_strings2(smartlist_t *sl, const char *join,
  *     printf("%d: %s\n", cp_sl_idx, cp);
  *     tor_free(cp);
  *   });
- *   smarlitst_free(list);
+ *   smartlist_free(list);
+ * </pre>
+ *
+ * Example use (advanced):
+ * <pre>
+ *   SMARTLIST_FOREACH(list, char *, cp,
+ *   {
+ *     if (!strcmp(cp, "junk")) {
+ *       smartlist_del(list, cp_sl_idx);
+ *       tor_free(cp);
+ *       --cp_sl_len; // decrement length of list so we don't run off the end
+ *       --cp_sl_idx; // decrement idx so we consider the item that moved here
+ *     }
+ *   });
  * </pre>
  */
 #define SMARTLIST_FOREACH(sl, type, var, cmd)                   \
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 0af144d23..5f023fa16 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -1023,8 +1023,7 @@ crypto_pk_get_fingerprint(crypto_pk_env_t *pk, char *fp_out, int add_space)
   }
   base16_encode(hexdigest,sizeof(hexdigest),digest,DIGEST_LEN);
   if (add_space) {
-    if (tor_strpartition(fp_out, FINGERPRINT_LEN+1, hexdigest, " ", 4,
-                         NEVER_TERMINATE)<0)
+    if (tor_strpartition(fp_out, FINGERPRINT_LEN+1, hexdigest, " ", 4)<0)
       return -1;
   } else {
     strncpy(fp_out, hexdigest, HEX_DIGEST_LEN+1);
diff --git a/src/common/crypto.h b/src/common/crypto.h
index f09936ef9..5257fd431 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -167,7 +167,8 @@ void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);
 int digest_to_base64(char *d64, const char *digest);
 int digest_from_base64(char *digest, const char *d64);
 
-/** DOCDOC */
+/** Length of RFC2440-style S2K specifier: the first 8 bytes are a salt, the
+ * 9th describes how much iteration to do. */
 #define S2K_SPECIFIER_LEN 9
 void secret_to_key(char *key_out, size_t key_out_len, const char *secret,
                    size_t secret_len, const char *s2k_specifier);
diff --git a/src/common/log.h b/src/common/log.h
index c6b6a6aa6..b2e957579 100644
--- a/src/common/log.h
+++ b/src/common/log.h
@@ -90,7 +90,7 @@
 /** Bandwidth accounting. */
 #define LD_ACCT     (1u<<17)
 
-/** DOCDOC */
+/** Callback type used for add_callback_log. */
 typedef void (*log_callback)(int severity, uint32_t domain, const char *msg);
 
 int parse_log_level(const char *level);
diff --git a/src/common/torgzip.h b/src/common/torgzip.h
index f8e15d75c..51e870930 100644
--- a/src/common/torgzip.h
+++ b/src/common/torgzip.h
@@ -12,7 +12,10 @@
 #define __TORGZIP_H
 #define TORGZIP_H_ID "$Id$"
 
-/** DOCDOC */
+/** Enumeration of what kind of compression to use.  Only ZLIB_METHOD is
+ * guaranteed to be supported by the compress/uncompress functions here;
+ * GZIP_METHOD may be supported if we built against zlib version 1.2 or later
+ * and is_gzip_supported() returns true. */
 typedef enum {
   NO_METHOD=0, GZIP_METHOD=1, ZLIB_METHOD=2, UNKNOWN_METHOD=3
 } compress_method_t;
@@ -32,10 +35,11 @@ int is_gzip_supported(void);
 
 compress_method_t detect_compression_method(const char *in, size_t in_len);
 
-/** DOCDOC */
+/** Return values from tor_zlib_process; see that function's documentation for
+ * details. */
 typedef enum {
   TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
-}  tor_zlib_output_t;
+} tor_zlib_output_t;
 typedef struct tor_zlib_state_t tor_zlib_state_t;
 tor_zlib_state_t *tor_zlib_new(int compress, compress_method_t method);
 
diff --git a/src/common/util.c b/src/common/util.c
index 6ecb901ea..a5b87c431 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -238,17 +238,12 @@ tor_strstrip(char *s, const char *strip)
  * string <b>s</b>, with the string <b>insert</b> inserted after every
  * <b>n</b> characters.  Return 0 on success, -1 on failure.
  *
- * If <b>rule</b> is ALWAYS_TERMINATE, then always end the string with
- * <b>insert</b>, even if its length is not a multiple of <b>n</b>.  If
- * <b>rule</b> is NEVER_TERMINATE, then never end the string with
- * <b>insert</b>, even if its length <i>is</i> a multiple of <b>n</b>.
- * If <b>rule</b> is TERMINATE_IF_EVEN, then end the string with <b>insert</b>
- * exactly when its length <i>is</i> a multiple of <b>n</b>.
+ * Never end the string with <b>insert</b>, even if its length <i>is</i> a
+ * multiple of <b>n</b>.
  */
 int
 tor_strpartition(char *dest, size_t dest_len,
-                 const char *s, const char *insert, size_t n,
-                 part_finish_rule_t rule)
+                 const char *s, const char *insert, size_t n)
 {
   char *destp;
   size_t len_in, len_out, len_ins;
@@ -264,17 +259,8 @@ tor_strpartition(char *dest, size_t dest_len,
   tor_assert(len_in/n < SIZE_T_CEILING/len_ins); /* avoid overflow */
   len_out = len_in + (len_in/n)*len_ins;
   is_even = (len_in%n) == 0;
-  switch (rule)
-    {
-    case ALWAYS_TERMINATE:
-      if (!is_even) len_out += len_ins;
-      break;
-    case NEVER_TERMINATE:
-      if (is_even && len_in) len_out -= len_ins;
-      break;
-    case TERMINATE_IF_EVEN:
-      break;
-    }
+  if (is_even && len_in)
+    len_out -= len_ins;
   if (dest_len < len_out+1)
     return -1;
   destp = dest;
@@ -283,10 +269,8 @@ tor_strpartition(char *dest, size_t dest_len,
     strncpy(destp, s, n);
     remaining -= n;
     if (remaining < 0) {
-      if (rule == ALWAYS_TERMINATE)
-        strncpy(destp+n+remaining,insert,len_ins+1);
       break;
-    } else if (remaining == 0 && rule == NEVER_TERMINATE) {
+    } else if (remaining == 0) {
       *(destp+n) = '\0';
       break;
     }
diff --git a/src/common/util.h b/src/common/util.h
index 868f4cde2..5b6dafdaa 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -39,13 +39,15 @@
 #error "Sorry; we don't support building with NDEBUG."
 #else
 #ifdef __GNUC__
-/** DOCDOC */
+/** Macro: evaluate the expression x, which we expect to be false.
+ * Used to hint the compiler that a branch won't be taken. */
 #define PREDICT_FALSE(x) PREDICT((x) == ((typeof(x)) 0), 0)
 #else
 #define PREDICT_FALSE(x) !(x)
 #endif
 
-/** DOCDOC */
+/** Like assert(3), but send assertion failures to the log as well as to
+ * stderr. */
 #define tor_assert(expr) do {                                           \
     if (PREDICT_FALSE(expr)) {                                          \
       log(LOG_ERR, LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
@@ -110,7 +112,7 @@ extern int dmalloc_free(const char *file, const int line, void *pnt,
 
 /* String manipulation */
 
-/** DOCDOC */
+/** Allowable characters in a hexadecimal string. */
 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
 void tor_strlower(char *s) ATTR_NONNULL((1));
 void tor_strupper(char *s) ATTR_NONNULL((1));
@@ -123,13 +125,8 @@ int strcmpend(const char *s1, const char *s2) ATTR_PURE ATTR_NONNULL((1,2));
 int strcasecmpend(const char *s1, const char *s2)
   ATTR_PURE ATTR_NONNULL((1,2));
 int tor_strstrip(char *s, const char *strip) ATTR_NONNULL((1,2));
-/** DOCDOC */
-typedef enum {
-  ALWAYS_TERMINATE, NEVER_TERMINATE, TERMINATE_IF_EVEN
-} part_finish_rule_t;
 int tor_strpartition(char *dest, size_t dest_len,
-                     const char *s, const char *insert, size_t n,
-                     part_finish_rule_t rule);
+                     const char *s, const char *insert, size_t n);
 long tor_parse_long(const char *s, int base, long min,
                     long max, int *ok, char **next);
 unsigned long tor_parse_ulong(const char *s, int base, unsigned long min,
@@ -169,11 +166,13 @@ int parse_iso_time(const char *buf, time_t *t);
 int write_all(int fd, const char *buf, size_t count, int isSocket);
 int read_all(int fd, char *buf, size_t count, int isSocket);
 
-/** DOCDOC */
-typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR} file_status_t;
+/** Return values from file_status(); see that function's documentation
+ * for details. */
+typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR } file_status_t;
 file_status_t file_status(const char *filename);
 
-/** DOCDOC */
+/** Possible behaviors for check_private_dir() on encountering a nonexistent
+ * directory; see that function's documentation for details. */
 typedef enum { CPD_NONE, CPD_CREATE, CPD_CHECK } cpd_check_t;
 int check_private_dir(const char *dirname, cpd_check_t check);
 int write_str_to_file(const char *fname, const char *str, int bin);
diff --git a/src/or/test.c b/src/or/test.c
index 77e6e9f2d..6de1ac7f1 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -654,17 +654,7 @@ test_util(void)
   test_streq(buf, "Testing123");
 
   /* Test tor_strpartition() */
-  test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefg", "##", 3,
-                                 TERMINATE_IF_EVEN));
-  test_streq(buf, "abc##def##g");
-  test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefg", "##", 3,
-                                 ALWAYS_TERMINATE));
-  test_streq(buf, "abc##def##g##");
-  test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3,
-                                 TERMINATE_IF_EVEN));
-  test_streq(buf, "abc##def##ghi##");
-  test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3,
-                                 NEVER_TERMINATE));
+  test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3));
   test_streq(buf, "abc##def##ghi");
 
   /* Test parse_addr_port */