[or-cvs] Document SMARTLIST_FOREACH macro, along with previously-nau...

[nickm@xxxxxxxx (Nick Mathewson)]

Update of /home/or/cvsroot/tor/src/common
In directory moria:/tmp/cvs-serv13545/src/common

Modified Files:
	container.h 
Log Message:
Document SMARTLIST_FOREACH macro, along with previously-naughty foo_sl_idx variable.

Index: container.h
===================================================================
RCS file: /home/or/cvsroot/tor/src/common/container.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- container.h	9 Sep 2005 23:12:54 -0000	1.15
+++ container.h	11 Sep 2005 23:14:14 -0000	1.16
@@ -64,6 +64,22 @@
 char *smartlist_join_strings2(smartlist_t *sl, const char *join,
                               size_t join_len, int terminate, size_t *len_out);
 
+/** 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.
+ *
+ * Example use:
+ * <pre>
+ *   smartlist_t *list = smartlist_split("A:B:C", ":", 0, 0);
+ *   SMARTLIST_FOREACH(list, char *, cp,
+ *   {
+ *     printf("%d: %s\n", cp_sl_idx, cp);
+ *     tor_free(cp);
+ *   });
+ *   smarlitst_free(list);
+ * </pre>
+ */
 #define SMARTLIST_FOREACH(sl, type, var, cmd)                   \
   do {                                                          \
     int var ## _sl_idx, var ## _sl_len=smartlist_len(sl);       \