Add documentation for the iterator macros.

src/taglist.h

@@ -61,14 +61,68 @@ INT32 Tag_Iterate_Things (const mtag_t tag, const size_t p);
 INT32 Tag_FindLineSpecial(const INT16 special, const mtag_t tag);
 INT32 P_FindSpecialLineFromTag(INT16 special, INT16 tag, INT32 start);
 
-// Use this macro to declare the iterator position variable.
+// Use this macro to declare an iterator position variable.
 #define TAG_ITER_DECLARECOUNTER(level) size_t ICNT_##level
 
-#define TAG_ITER(level, fn, tag, id) for(ICNT_##level = 0; (id = fn(tag, ICNT_##level)) >= 0; ICNT_##level++)
+#define TAG_ITER(level, fn, tag, return_varname) for(ICNT_##level = 0; (return_varname = fn(tag, ICNT_##level)) >= 0; ICNT_##level++)
 
-// Use these macros as wrappers for the taglist iterations.
-#define TAG_ITER_SECTORS(level, tag, id) TAG_ITER(level, Tag_Iterate_Sectors, tag, id)
-#define TAG_ITER_LINES(level, tag, id)   TAG_ITER(level, Tag_Iterate_Lines, tag, id)
-#define TAG_ITER_THINGS(level, tag, id)  TAG_ITER(level, Tag_Iterate_Things, tag, id)
+// Use these macros as wrappers for a taglist iteration.
+#define TAG_ITER_SECTORS(level, tag, return_varname) TAG_ITER(level, Tag_Iterate_Sectors, tag, return_varname)
+#define TAG_ITER_LINES(level, tag, return_varname)   TAG_ITER(level, Tag_Iterate_Lines, tag, return_varname)
+#define TAG_ITER_THINGS(level, tag, return_varname)  TAG_ITER(level, Tag_Iterate_Things, tag, return_varname)
+
+/* ITERATION MACROS
+TAG_ITER_DECLARECOUNTER must be used before using the iterators.
+
+'level':
+For each nested iteration, an additional TAG_ITER_DECLARECOUNTER
+must be used with a different level number to avoid conflict with
+the outer iterations.
+Most cases don't have nested iterations and thus the level is just 0.
+
+'tag':
+Pretty much the elements' tag to iterate through.
+
+'return_varname':
+Target variable's name to return the iteration results to.
+
+
+EXAMPLE:
+{
+	TAG_ITER_DECLARECOUNTER(0);
+	TAG_ITER_DECLARECOUNTER(1); // For the nested iteration.
+
+	size_t li;
+	size_t sec;
+
+	INT32 tag1 = 4;
+
+	...
+
+	TAG_ITER_LINES(0, tag1, li)
+	{
+		line_t *line = lines + li;
+
+		...
+
+		if (something)
+		{
+			mtag_t tag2 = 8;
+
+			// Nested iteration; just make sure the level is higher
+			// and that it has its own counter declared in scope.
+			TAG_ITER_SECTORS(1, tag2, sec)
+			{
+				sector_t *sector = sectors + sec;
+
+				...
+			}
+		}
+	}
+}
+
+Notes:
+If no elements are found for a given tag, the loop inside won't be executed.
+*/
 
 #endif //__R_TAGLIST__