[PATCH libnetfilter_queue 15/32] doc: Eliminate doxygen warnings from linux_list.h

[Duncan Roe <duncan_roe@optusnet.com.au>]

The warnings concerned prefetch(), LIST_POISON1 & LIST_POISON2.
Remove all 3 macros since they do nothing useful in userspace programs.
Also take a few doxygen comment improvements from 6.6 Linux source.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 include/libnetfilter_queue/linux_list.h | 44 ++++++++++++-------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/include/libnetfilter_queue/linux_list.h b/include/libnetfilter_queue/linux_list.h
index 88ea386..500481d 100644
--- a/include/libnetfilter_queue/linux_list.h
+++ b/include/libnetfilter_queue/linux_list.h
@@ -10,10 +10,20 @@
  * This is a cut-down copy of libnfnetlink/include/linux_list.h which is itself
  * an old snapshot of linux/include/linux/list.h.
  * This file only contains what we use.
+ *
+ * 2024-01-27 12:45:41 +1100 duncan_roe@optusnet.com.au
+ * LIST_POISONx doesn't really work for user space - just use NULL
+ *
+ * 2024-01-27 18:16:51 +1100 duncan_roe@optusnet.com.au
+ * I can't see how the prefetch() calls do any good so remove them
+ * and #define of prefetch
+ *
+ * 2024-01-27 18:53:46 +1100 duncan_roe@optusnet.com.au
+ * Take a few doxygen comment improvements from 6.6 Linux source
  */
 
 /**
- * \defgroup List Simple doubly linked list implementation
+ * \defgroup List Circular doubly linked list implementation
  * @{
  */
 
@@ -30,18 +40,8 @@
 	typeof( ((type *)0)->member ) *__mptr = (ptr);	\
 	(type *)( (char *)__mptr - offsetof(type,member) );})
 
-#define prefetch(x) ((void)0)
-
 /*
- * These are non-NULL pointers that will result in page faults
- * under normal circumstances, used to verify that nobody uses
- * non-initialized list entries.
- */
-#define LIST_POISON1  ((void *) 0x00100100)
-#define LIST_POISON2  ((void *) 0x00200200)
-
-/*
- * Simple doubly linked list implementation.
+ * Circular doubly linked list implementation.
  *
  * Some of the internal functions ("__xxx") are useful when
  * manipulating whole lists rather than single entries, as
@@ -123,8 +123,8 @@ static inline void __list_del(struct list_head * prev, struct list_head * next)
 static inline void list_del(struct list_head *entry)
 {
 	__list_del(entry->prev, entry->next);
-	entry->next = LIST_POISON1;
-	entry->prev = LIST_POISON2;
+	entry->next = NULL;
+	entry->prev = NULL;
 }
 
 /**
@@ -139,30 +139,28 @@ static inline int list_empty(const struct list_head *head)
  * list_entry - get the struct for this entry
  * \param ptr:	the &struct list_head pointer.
  * \param type:	the type of the struct this is embedded in.
- * \param member:	the name of the list_struct within the struct.
+ * \param member:	the name of the list_head within the struct.
  */
 #define list_entry(ptr, type, member) \
 	container_of(ptr, type, member)
 
 /**
  * list_for_each_entry	-	iterate over list of given type
- * \param pos:	the type * to use as a loop counter.
+ * \param pos:	the type * to use as a loop cursor.
  * \param head:	the head for your list.
- * \param member:	the name of the list_struct within the struct.
+ * \param member:	the name of the list_head within the struct.
  */
 #define list_for_each_entry(pos, head, member)				\
-	for (pos = list_entry((head)->next, typeof(*pos), member),	\
-		     prefetch(pos->member.next);			\
+	for (pos = list_entry((head)->next, typeof(*pos), member);	\
 	     &pos->member != (head); 					\
-	     pos = list_entry(pos->member.next, typeof(*pos), member),	\
-		     prefetch(pos->member.next))
+	     pos = list_entry(pos->member.next, typeof(*pos), member))	\
 
 /**
  * list_for_each_entry_safe - iterate over list of given type safe against removal of list entry
- * \param pos:	the type * to use as a loop counter.
+ * \param pos:	the type * to use as a loop cursor.
  * \param n:		another type * to use as temporary storage
  * \param head:	the head for your list.
- * \param member:	the name of the list_struct within the struct.
+ * \param member:	the name of the list_head within the struct.
  */
 #define list_for_each_entry_safe(pos, n, head, member)			\
 	for (pos = list_entry((head)->next, typeof(*pos), member),	\
-- 
2.35.8