[PATCH libnetfilter_queue 14/32] doc: Add linux_list.h to the doxygen system

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

Produce web and man pages for list_for_each_entry() and other macros.
Mostly a straight conversion of the kerneldoc but also document
struct list_head and macro INIT_LIST_HEAD.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/Makefile.am                     |  1 +
 doxygen/build_man.sh                    |  7 ++-
 doxygen/doxygen.cfg.in                  |  5 ++-
 include/libnetfilter_queue/linux_list.h | 60 +++++++++++++++++--------
 4 files changed, 52 insertions(+), 21 deletions(-)

diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 68be963..6135f25 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -8,6 +8,7 @@ doc_srcs = $(top_srcdir)/src/libnetfilter_queue.c\
            $(top_srcdir)/src/extra/ipv6.c\
            $(top_srcdir)/src/extra/tcp.c\
            $(top_srcdir)/src/extra/udp.c\
+           $(top_srcdir)/include/libnetfilter_queue/linux_list.h\
            $(top_srcdir)/src/extra/icmp.c
 
 doxyfile.stamp: $(doc_srcs) Makefile build_man.sh
diff --git a/doxygen/build_man.sh b/doxygen/build_man.sh
index 7eab8fa..643ad42 100755
--- a/doxygen/build_man.sh
+++ b/doxygen/build_man.sh
@@ -84,7 +84,12 @@ post_process(){
 
 make_man7(){
   popd >/dev/null
-  target=$(grep -Ew INPUT doxygen.cfg | rev | cut -f1 -d' ' | rev)/$2
+
+  # This grep command works for multiple directories on the INPUT line,
+  # as long as the directory containing the source with the main page
+  # comes first.
+  target=/$(grep -Ew INPUT doxygen.cfg | cut -f2- -d/ | cut -f1 -d' ')/$2
+
   mypath=$(dirname $0)
 
   # Build up temporary source in temp.c
diff --git a/doxygen/doxygen.cfg.in b/doxygen/doxygen.cfg.in
index fcfc045..e69dcd7 100644
--- a/doxygen/doxygen.cfg.in
+++ b/doxygen/doxygen.cfg.in
@@ -5,8 +5,9 @@ ABBREVIATE_BRIEF       =
 FULL_PATH_NAMES        = NO
 TAB_SIZE               = 8
 OPTIMIZE_OUTPUT_FOR_C  = YES
-INPUT                  = @abs_top_srcdir@/src
-FILE_PATTERNS          = *.c
+INPUT                  = @abs_top_srcdir@/src \
+                         @abs_top_srcdir@/include/libnetfilter_queue
+FILE_PATTERNS          = *.c linux_list.h
 RECURSIVE              = YES
 EXCLUDE_SYMBOLS        = EXPORT_SYMBOL \
                          tcp_word_hdr \
diff --git a/include/libnetfilter_queue/linux_list.h b/include/libnetfilter_queue/linux_list.h
index eaa9c07..88ea386 100644
--- a/include/libnetfilter_queue/linux_list.h
+++ b/include/libnetfilter_queue/linux_list.h
@@ -12,17 +12,23 @@
  * This file only contains what we use.
  */
 
+/**
+ * \defgroup List Simple doubly linked list implementation
+ * @{
+ */
+
+
 /**
  * container_of - cast a member of a structure out to the containing structure
  *
- * @ptr:	the pointer to the member.
- * @type:	the type of the container struct this is embedded in.
- * @member:	the name of the member within the struct.
+ * \param ptr:	the pointer to the member.
+ * \param type:	the type of the container struct this is embedded in.
+ * \param member:	the name of the member within the struct.
  *
  */
 #define container_of(ptr, type, member) ({			\
-        typeof( ((type *)0)->member ) *__mptr = (ptr);	\
-        (type *)( (char *)__mptr - offsetof(type,member) );})
+	typeof( ((type *)0)->member ) *__mptr = (ptr);	\
+	(type *)( (char *)__mptr - offsetof(type,member) );})
 
 #define prefetch(x) ((void)0)
 
@@ -44,10 +50,24 @@
  * using the generic single-entry routines.
  */
 
+/**
+ * \struct list_head
+ * Link to adjacent members of the circular list
+ * \note Each member of a list must start with this structure
+ * (containing structures OK)
+ * \var list_head::next
+ * pointer to the next list member
+ * \var list_head::prev
+ * pointer to the previous list member
+ */
 struct list_head {
 	struct list_head *next, *prev;
 };
 
+/**
+ * INIT_LIST_HEAD - Initialise first member of a new list
+ * \param ptr the &struct list_head pointer.
+ */
 #define INIT_LIST_HEAD(ptr) do { \
 	(ptr)->next = (ptr); (ptr)->prev = (ptr); \
 } while (0)
@@ -70,8 +90,8 @@ static inline void __list_add(struct list_head *new,
 
 /**
  * list_add - add a new entry
- * @new: new entry to be added
- * @head: list head to add it after
+ * \param new: new entry to be added
+ * \param head: list head to add it after
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -96,7 +116,7 @@ static inline void __list_del(struct list_head * prev, struct list_head * next)
 
 /**
  * list_del - deletes entry from list.
- * @entry: the element to delete from the list.
+ * \param entry: the element to delete from the list.
  * Note: list_empty on entry does not return true after this, the entry is
  * in an undefined state.
  */
@@ -117,18 +137,18 @@ static inline int list_empty(const struct list_head *head)
 }
 /**
  * list_entry - get the struct for this entry
- * @ptr:	the &struct list_head pointer.
- * @type:	the type of the struct this is embedded in.
- * @member:	the name of the list_struct within the struct.
+ * \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.
  */
 #define list_entry(ptr, type, member) \
 	container_of(ptr, type, member)
 
 /**
  * list_for_each_entry	-	iterate over list of given type
- * @pos:	the type * to use as a loop counter.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * \param pos:	the type * to use as a loop counter.
+ * \param head:	the head for your list.
+ * \param member:	the name of the list_struct within the struct.
  */
 #define list_for_each_entry(pos, head, member)				\
 	for (pos = list_entry((head)->next, typeof(*pos), member),	\
@@ -139,10 +159,10 @@ static inline int list_empty(const struct list_head *head)
 
 /**
  * list_for_each_entry_safe - iterate over list of given type safe against removal of list entry
- * @pos:	the type * to use as a loop counter.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * \param pos:	the type * to use as a loop counter.
+ * \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.
  */
 #define list_for_each_entry_safe(pos, n, head, member)			\
 	for (pos = list_entry((head)->next, typeof(*pos), member),	\
@@ -150,4 +170,8 @@ static inline int list_empty(const struct list_head *head)
 	     &pos->member != (head); 					\
 	     pos = n, n = list_entry(n->member.next, typeof(*n), member))
 
+/**
+ * @}
+ */
+
 #endif
-- 
2.35.8