From 11f146a06f5b52867197ffddffcbe97d58366f31 Mon Sep 17 00:00:00 2001
From: Pavel Charvat <pchar@ucw.cz>
Date: Thu, 6 Nov 2008 15:44:30 +0100
Subject: [PATCH] Doc: More bits about linked lists.

---
 ucw/clists.h       | 19 +++++++++++++++++++
 ucw/simple-lists.h | 29 +++++++++++++++++++++++++++++
 ucw/slists.h       | 12 ++++++++++++
 3 files changed, 60 insertions(+)

diff --git a/ucw/clists.h b/ucw/clists.h
index bc8779d9..919abc07 100644
--- a/ucw/clists.h
+++ b/ucw/clists.h
@@ -73,11 +73,30 @@ static inline int clist_empty(clist *l)
   return (l->head.next == &l->head);
 }
 
+/**
+ * Loop over all nodes in the @list and perform the next C statement on them. The current node is stored in @n which must be defined before as pointer to any type.
+ * The list should not be changed during this loop command.
+ **/
 #define CLIST_WALK(n,list) for(n=(void*)(list).head.next; (cnode*)(n) != &(list).head; n=(void*)((cnode*)(n))->next)
+
+/**
+ * Same as @CLIST_WALK(), but allows removal of the current node. This macro requires one more variable to store some temporary pointers.
+ **/
 #define CLIST_WALK_DELSAFE(n,list,tmp) for(n=(void*)(list).head.next; tmp=(void*)((cnode*)(n))->next, (cnode*)(n) != &(list).head; n=(void*)tmp)
+
+/**
+ * Same as @CLIST_WALK(), but it defines the variable for the current node in place. @type should be a pointer type.
+ **/
 #define CLIST_FOR_EACH(type,n,list) for(type n=(void*)(list).head.next; (cnode*)(n) != &(list).head; n=(void*)((cnode*)(n))->next)
+
+/**
+ * Same as @CLIST_WALK_DELSAFE(), but it defines the variable for the current node in place. @type should be a pointer type. The temporary variable must be still known before.
+ **/
 #define CLIST_FOR_EACH_DELSAFE(type,n,list,tmp) for(type n=(void*)(list).head.next; tmp=(void*)((cnode*)(n))->next, (cnode*)(n) != &(list).head; n=(void*)tmp)
 
+/**
+ * Reversed version of @CLIST_FOR_EACH().
+ **/
 #define CLIST_FOR_EACH_BACKWARDS(type,n,list) for(type n=(void*)(list).head.prev; (cnode*)(n) != &(list).head; n=(void*)((cnode*)(n))->prev)
 
 /**
diff --git a/ucw/simple-lists.h b/ucw/simple-lists.h
index e8bf6251..64b81901 100644
--- a/ucw/simple-lists.h
+++ b/ucw/simple-lists.h
@@ -12,6 +12,16 @@
 
 #include "ucw/clists.h"
 
+/***
+ * To simplify very common usage of circular linked links, whose nodes can hold only one or two trivial values,
+ * we define some generic node types, called the simple nodes.
+ *
+ * To avoid some type casts, values in simple nodes are defined as unions of most frequent types.
+ ***/
+
+/**
+ * Simple node with one value.
+ **/
 typedef struct simp_node {
   cnode n;
   union {
@@ -22,6 +32,9 @@ typedef struct simp_node {
   };
 } simp_node;
 
+/**
+ * Simple node with two values.
+ **/
 typedef struct simp2_node {
   cnode n;
   union {
@@ -39,11 +52,27 @@ typedef struct simp2_node {
 } simp2_node;
 
 struct mempool;
+
+/**
+ * Allocate a new one-value node on memory pool @mp and insert it to @l. The value is undefined and should be changed afterwards.
+ **/
 simp_node *simp_append(struct mempool *mp, clist *l);
+
+/**
+ * Allocate a new two-value node on memory pool @mp and insert it to @l. The values are undefined and should be changed afterwards.
+ **/
 simp2_node *simp2_append(struct mempool *mp, clist *l);
 
 /* Configuration sections */
+
+/**
+ * Default definition of the configuration section with one-value string node. Identifier of the value is `String`.
+ **/
 extern struct cf_section cf_string_list_config;
+
+/**
+ * Default definition of the configuration section with two-value string node. Identifiers of the values are `Src` and `Dest`.
+ **/
 extern struct cf_section cf_2string_list_config;
 
 #endif
diff --git a/ucw/slists.h b/ucw/slists.h
index bdab355d..5c6d29f9 100644
--- a/ucw/slists.h
+++ b/ucw/slists.h
@@ -123,8 +123,20 @@ static inline void slist_remove_head(slist *l)
 
 /* Loops */
 
+/**
+ * Loop over all nodes in the @list and perform the next C statement on them. The current node is stored in @n which must be defined before as pointer to any type.
+ * The list should not be changed during this loop command.
+ **/
 #define SLIST_WALK(n,list) for(n=(void*)(list).head.next; (n); (n)=(void*)((snode*)(n))->next)
+
+/**
+ * Same as @SLIST_WALK(), but allows removal of the current node. This macro requires one more variable to store the pointer to the previous node (useful for @slist_remove_after()).
+ **/
 #define SLIST_WALK_DELSAFE(n,list,prev) for((prev)=(void*)&(list).head; (n)=(void*)((snode*)prev)->next; (prev)=(((snode*)(prev))->next==(snode*)(n) ? (void*)(n) : (void*)(prev)))
+
+/**
+ * Same as @SLIST_WALK(), but it defines the variable for the current node in place. @type should be a pointer type.
+ **/
 #define SLIST_FOR_EACH(type,n,list) for(type n=(void*)(list).head.next; n; n=(void*)((snode*)(n))->next)
 
 /* Non-trivial functions */
-- 
2.39.2