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@xxxxxxxxxxxxxxx>
---
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
