[PATCH libnetfilter_queue 16/32] doc: Eliminate doxygen warnings from iftable.c

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

Introduce some new doxygen content. Not yet converted to use libmnl.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/Makefile.am    |  1 +
 doxygen/doxygen.cfg.in |  2 ++
 src/iftable.c          | 53 +++++++++++++++++++++++++-----------------
 3 files changed, 35 insertions(+), 21 deletions(-)

diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 6135f25..aae1ccc 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -2,6 +2,7 @@ if HAVE_DOXYGEN
 
 doc_srcs = $(top_srcdir)/src/libnetfilter_queue.c\
            $(top_srcdir)/src/nlmsg.c\
+           $(top_srcdir)/src/iftable.c\
            $(top_srcdir)/src/extra/checksum.c\
            $(top_srcdir)/src/extra/ipv4.c\
            $(top_srcdir)/src/extra/pktbuff.c\
diff --git a/doxygen/doxygen.cfg.in b/doxygen/doxygen.cfg.in
index e69dcd7..c795df1 100644
--- a/doxygen/doxygen.cfg.in
+++ b/doxygen/doxygen.cfg.in
@@ -17,6 +17,8 @@ EXCLUDE_SYMBOLS        = EXPORT_SYMBOL \
                          nfnl_handle \
                          nfnl_subsys_handle \
                          mnl_socket \
+                         ifindex_node \
+                         nlif_handle \
                          nfnl_callback2 \
                          tcp_flag_word
 EXAMPLE_PATTERNS       =
diff --git a/src/iftable.c b/src/iftable.c
index aab59b3..22c3952 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -2,6 +2,7 @@
  *
  * (C) 2004 by Astaro AG, written by Harald Welte <hwelte@astaro.com>
  * (C) 2008 by Pablo Neira Ayuso <pablo@netfilter.org>
+ * (C) 2024 by Duncan Roe <duncan_roe@optusnet.com.au>
  *
  * This software is Free Software and licensed under GNU GPLv2+.
  */
@@ -25,11 +26,14 @@
 #include "linux_list.h"
 
 /**
- * \defgroup iftable Functions in iftable.c [DEPRECATED]
- * This documentation is provided for the benefit of maintainers of legacy code.
+ * \defgroup iftable Functions to manage a table of network interfaces
+ * These functions maintain a database of the name and flags of each
+ * network interface.
  *
- * New applications should use
- * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
+ * mnl API programs may instead use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/)
+ * calls directly to maintain an
+ * interface table with more (or less!) data points, e.g. MTU.
  * @{
  */
 
@@ -52,8 +56,8 @@ struct nlif_handle {
 };
 
 /* iftable_add - Add/Update an entry to/in the interface table
- * @n:		netlink message header of a RTM_NEWLINK message
- * @arg:	not used
+ * \param n:	netlink message header of a RTM_NEWLINK message
+ * \param arg:	not used
  *
  * This function adds/updates an entry in the intrface table.
  * Returns -1 on error, 1 on success.
@@ -114,8 +118,8 @@ static int iftable_add(struct nlmsghdr *n, void *arg)
 }
 
 /* iftable_del - Delete an entry from the interface table
- * @n:		netlink message header of a RTM_DELLINK nlmsg
- * @arg:	not used
+ * \param n:	netlink message header of a RTM_DELLINK nlmsg
+ * \param arg:	not used
  *
  * Delete an entry from the interface table.  
  * Returns -1 on error, 0 if no matching entry was found or 1 on success.
@@ -148,9 +152,10 @@ static int iftable_del(struct nlmsghdr *n, void *arg)
 	return 0;
 }
 
-/** Get the name for an ifindex
+/**
+ * nlif_index2name - get the name for an ifindex
  *
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
  * \param index ifindex to be resolved
  * \param name interface name, pass a buffer of IFNAMSIZ size
  * \return -1 on error, 1 on success 
@@ -182,9 +187,10 @@ int nlif_index2name(struct nlif_handle *h,
 	return -1;
 }
 
-/** Get the flags for an ifindex
+/**
+ * nlif_get_ifflags - get the flags for an ifindex
  *
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
  * \param index ifindex to be resolved
  * \param flags pointer to variable used to store the interface flags
  * \return -1 on error, 1 on success 
@@ -215,7 +221,8 @@ int nlif_get_ifflags(const struct nlif_handle *h,
 	return -1;
 }
 
-/** Initialize interface table
+/**
+ * nlif_open - initialize interface table
  *
  * Initialize rtnl interface and interface table
  * Call this before any nlif_* function
@@ -262,10 +269,10 @@ err:
 	return NULL;
 }
 
-/** Destructor of interface table
+/**
+ * nlif_close - free all resources associated with the interface table
  *
- * \param nlif_handle A pointer to a ::nlif_handle created 
- * via nlif_open()
+ * \param h pointer to nlif_handle created by nlif_open()
  */
 void nlif_close(struct nlif_handle *h)
 {
@@ -289,9 +296,12 @@ void nlif_close(struct nlif_handle *h)
 	h = NULL; /* bugtrap */
 }
 
-/** Receive message from netlink and update interface table
+/**
+ * nlif_catch - receive message from netlink and update interface table
+ *
+ * FIXME - elaborate a bit
  *
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
  * \return 0 if OK
  */
 int nlif_catch(struct nlif_handle *h)
@@ -316,7 +326,7 @@ static int nlif_catch_multi(struct nlif_handle *h)
 
 /** 
  * nlif_query - request a dump of interfaces available in the system
- * @h: pointer to a valid nlif_handler
+ * \param h: pointer to a valid nlif_handler
  */
 int nlif_query(struct nlif_handle *h)
 {
@@ -328,9 +338,10 @@ int nlif_query(struct nlif_handle *h)
 	return nlif_catch_multi(h);
 }
 
-/** Returns socket descriptor for the netlink socket
+/**
+ * nlif_fd - get file descriptor for the netlink socket
  *
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
  * \return The fd or -1 if there's an error
  */
 int nlif_fd(struct nlif_handle *h)
-- 
2.35.8