[or-cvs] r14298: Better macro documentation (in tor/trunk: . src/common)

[nickm@xxxxxxxx]

Author: nickm
Date: 2008-04-04 17:18:51 -0400 (Fri, 04 Apr 2008)
New Revision: 14298

Modified:
   tor/trunk/
   tor/trunk/src/common/container.h
Log:
 r19201@catbus:  nickm | 2008-04-04 14:23:19 -0400
 Better macro documentation



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

Modified: tor/trunk/src/common/container.h
===================================================================
--- tor/trunk/src/common/container.h	2008-04-03 19:01:16 UTC (rev 14297)
+++ tor/trunk/src/common/container.h	2008-04-04 21:18:51 UTC (rev 14298)
@@ -155,14 +155,46 @@
  *   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
+ *       SMARTLIST_DEL_CURRENT(list, cp);
  *     }
  *   });
  * </pre>
  */
+/* Note: these macros use token pasting, and reach into smartlist internals.
+ * This can make them a little daunting. Here's the approximate unpacking of
+ * the above examples, for entertainment value:
+ *
+ * <pre>
+ * smartlist_t *list = smartlist_split("A:B:C", ":", 0, 0);
+ * {
+ *   int cp_sl_idx, cp_sl_len = smartlist_len(list);
+ *   char *cp;
+ *   for (cp_sl_idx = 0; cp_sl_idx < cp_sl_len; ++cp_sl_idx) {
+ *     cp = smartlist_get(list, cp_sl_idx);
+ *     printf("%d: %s\n", cp_sl_idx, cp);
+ *     tor_free(cp);
+ *   }
+ * }
+ * smartlist_free(list);
+ * </pre>
+ *
+ * <pre>
+ * {
+ *   int cp_sl_idx, cp_sl_len = smartlist_len(list);
+ *   char *cp;
+ *   for (cp_sl_idx = 0; cp_sl_idx < cp_sl_len; ++cp_sl_idx) {
+ *     cp = smartlist_get(list, cp_sl_idx);
+ *     if (!strcmp(cp, "junk")) {
+ *       tor_free(cp);
+ *       smartlist_del(list, cp_sl_idx);
+ *       --cp_sl_idx;
+ *       --cp_sl_len;
+ *     }
+ *   }
+ * }
+ * </pre>
+ */
 #define SMARTLIST_FOREACH(sl, type, var, cmd)                   \
   STMT_BEGIN                                                    \
     int var ## _sl_idx, var ## _sl_len=(sl)->num_used;          \
@@ -217,6 +249,20 @@
  *     // use k and r
  *   } MAP_FOREACH_END.
  */
+/* Unpacks to, approximately:
+ * {
+ *   digestmap_iter_t *k_iter;
+ *   for (k_iter = digestmap_iter_init(m); !digestmap_iter_done(k_iter);
+ *        k_iter = digestmap_iter_next(m, k_iter)) {
+ *     const char *k;
+ *     void *r_voidp;
+ *     routerinfo_t *r;
+ *     digestmap_iter_get(k_iter, &k, &r_voidp);
+ *     r = r_voidp;
+ *     // use k and r
+ *   }
+ * }
+ */
 #define MAP_FOREACH(prefix, map, keytype, keyvar, valtype, valvar)      \
   STMT_BEGIN                                                            \
     prefix##iter_t *keyvar##_iter;                                      \
@@ -238,6 +284,25 @@
  *       MAP_DEL_CURRENT(k);
  *   } MAP_FOREACH_END.
  **/
+/* Unpacks to, approximately:
+ * {
+ *   digestmap_iter_t *k_iter;
+ *   int k_del=0;
+ *   for (k_iter = digestmap_iter_init(m); !digestmap_iter_done(k_iter);
+ *        k_iter = k_del ? digestmap_iter_next(m, k_iter)
+ *                       : digestmap_iter_next_rmv(m, k_iter)) {
+ *     const char *k;
+ *     void *r_voidp;
+ *     routerinfo_t *r;
+ *     k_del=0;
+ *     digestmap_iter_get(k_iter, &k, &r_voidp);
+ *     r = r_voidp;
+ *     if (is_very_old(r)) {
+ *       k_del = 1;
+ *     }
+ *   }
+ * }
+ */
 #define MAP_FOREACH_MODIFY(prefix, map, keytype, keyvar, valtype, valvar) \
   STMT_BEGIN                                                            \
     prefix##iter_t *keyvar##_iter;                                      \