[PATCH libnetfilter_queue v3 0/1] src: doc: Insert SYNOPSIS sections for man pages

[PATCH libnetfilter_queue v3 0/1] src: doc: Insert SYNOPSIS sections for man pages

[Duncan Roe]

Here's a simple way to test this patch and the associated
"Fix NAME entry in man pages" patch.

1. Apply the 2 above-mentioned patches

2. Build the result.

3. Ensure environment variable MANPATH starts with the 'man' directory you just
   built.

4. Issue the following:

man nfq_create_queue nfq_get_gid pktb_alloc nfq_tcp_get_hdr nfq_udp_get_hdr\
nfq_nlmsg_verdict_put nfq_bind_pf nfq_ip_get_hdr nfq_ip6_get_hdr\
pktb_mac_header nfq_nlmsg_cfg_put_cmd pktb_pull nfq_udp_compute_checksum_ipv4\
nfq_tcp_compute_checksum_ipv4 nfq_snprintf_xml nfq_nlmsg_parse\
nfq_icmp_get_hdr nfq_ip_set_checksum

5. 'q' each man page to see the next (maybe ':n' on some systems).
   Verify for correct synopsis and general appearance.
   (If the page is shorter than screen lines, 'g' should put it at top).

Duncan Roe (1):
  src: doc: Insert SYNOPSIS sections for man pages

 src/extra/icmp.c         |  9 +++++++++
 src/extra/ipv4.c         | 20 +++++++++++++++++++-
 src/extra/ipv6.c         | 11 +++++++++++
 src/extra/pktbuff.c      | 37 +++++++++++++++++++++++++++++++------
 src/extra/tcp.c          | 20 ++++++++++++++++++++
 src/extra/udp.c          | 20 ++++++++++++++++++++
 src/libnetfilter_queue.c | 40 ++++++++++++++++++++++++++++++++++++++--
 src/nlmsg.c              | 28 ++++++++++++++++++++++++++++
 8 files changed, 176 insertions(+), 9 deletions(-)

-- 
2.17.5

[PATCH libnetfilter_queue v3 1/1] src: doc: Insert SYNOPSIS sections for man pages

[Duncan Roe]

In order to work with the post-processing logic in doxygen/Makefile.am,
SYNOPSIS sections must be inserted at the end of the module description
(text after \defgroup or \addtogroup)
(becomes Detailed Description in the man page).

Also a few minor updates including rename module uselessfns to do_not_use.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
v2: Rebase after "deprecate libnetfilter_queue/linux_nfnetlink_queue.h" patch
v3: Add extra #include lines to synopses as required by above patch
 src/extra/icmp.c         |  9 +++++++++
 src/extra/ipv4.c         | 20 +++++++++++++++++++-
 src/extra/ipv6.c         | 11 +++++++++++
 src/extra/pktbuff.c      | 37 +++++++++++++++++++++++++++++++------
 src/extra/tcp.c          | 20 ++++++++++++++++++++
 src/extra/udp.c          | 20 ++++++++++++++++++++
 src/libnetfilter_queue.c | 40 ++++++++++++++++++++++++++++++++++++++--
 src/nlmsg.c              | 28 ++++++++++++++++++++++++++++
 8 files changed, 176 insertions(+), 9 deletions(-)

diff --git a/src/extra/icmp.c b/src/extra/icmp.c
index a97979b..eaade7b 100644
--- a/src/extra/icmp.c
+++ b/src/extra/icmp.c
@@ -19,6 +19,15 @@
 
 /**
  * \defgroup icmp ICMP helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/libnetfilter_queue_icmp.h>
+\endmanonly
+ *
  * @{
  */
 
diff --git a/src/extra/ipv4.c b/src/extra/ipv4.c
index af4482d..58fb471 100644
--- a/src/extra/ipv4.c
+++ b/src/extra/ipv4.c
@@ -23,6 +23,15 @@
 
 /**
  * \defgroup ipv4 IPv4 helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/libnetfilter_queue_ipv4.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -87,6 +96,15 @@ int nfq_ip_set_transport_header(struct pkt_buff *pktb, struct iphdr *iph)
  * \defgroup ip_internals Internal IP functions
  *
  * Most user-space programs will never need these.
+ *
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/libnetfilter_queue_ipv4.h>
+\endmanonly
  *
  * @{
  */
@@ -143,7 +161,7 @@ int nfq_ip_mangle(struct pkt_buff *pktb, unsigned int dataoff,
 }
 
 /**
- * nfq_pkt_snprintf_ip - print IPv4 header into buffer in iptables LOG format
+ * nfq_ip_snprintf - print IPv4 header into buffer in iptables LOG format
  * \param buf: Pointer to buffer that will be used to print the header
  * \param size: Size of the buffer (or remaining room in it)
  * \param iph: Pointer to a valid IPv4 header
diff --git a/src/extra/ipv6.c b/src/extra/ipv6.c
index 40b9950..69d86a8 100644
--- a/src/extra/ipv6.c
+++ b/src/extra/ipv6.c
@@ -24,6 +24,17 @@
 
 /**
  * \defgroup ipv6 IPv6 helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <arpa/inet.h>
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue_ipv6.h>
+\endmanonly
+ *
  * @{
  */
 
diff --git a/src/extra/pktbuff.c b/src/extra/pktbuff.c
index 9bdc6bd..005172c 100644
--- a/src/extra/pktbuff.c
+++ b/src/extra/pktbuff.c
@@ -23,8 +23,17 @@
 /**
  * \defgroup pktbuff User-space network packet buffer
  *
- * This library provides the user-space network packet buffer. This abstraction
- * is strongly inspired by Linux kernel network buffer, the so-called sk_buff.
+ * These functions provide the user-space network packet buffer.
+ * This abstraction is strongly inspired by Linux kernel network buffer,
+ * the so-called sk_buff.
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/pktbuff.h>
+\endmanonly
  *
  * @{
  */
@@ -150,20 +159,36 @@ void pktb_free(struct pkt_buff *pktb)
  * \n
  * 1. Functions to get values of members of opaque __struct pktbuff__, described
  * below
- * \n
+ *
  * 2. Internal functions, described in Module __Internal functions__
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/pktbuff.h>
+\endmanonly
  *
  * @{
  */
 
 /**
- * \defgroup uselessfns Internal functions
+ * \defgroup do_not_use Internal functions
  *
- * \warning Do not use these functions. Instead, always use the mangle
+ * Do not use these functions. Instead, always use the mangle
  * function appropriate to the level at which you are working.
  * \n
  * pktb_mangle() uses all the below functions except _pktb_pull_, which is not
  * used by anything.
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/pktbuff.h>
+\endmanonly
  *
  * @{
  */
@@ -317,7 +342,7 @@ static int enlarge_pkt(struct pkt_buff *pktb, unsigned int extra)
  * excess of \b rep_len over \b match_len
  \warning pktb_mangle does not update any checksums. Developers should use the
  appropriate mangler for the protocol level: nfq_ip_mangle(),
- nfq_tcp_mangle_ipv4() or nfq_udp_mangle_ipv4(). IPv6 versions are planned.
+ nfq_tcp_mangle_ipv4(), nfq_udp_mangle_ipv4() or IPv6 variants.
  \n
  It is appropriate to use pktb_mangle to change the MAC header.
  */
diff --git a/src/extra/tcp.c b/src/extra/tcp.c
index 01bfe8c..720afd2 100644
--- a/src/extra/tcp.c
+++ b/src/extra/tcp.c
@@ -29,6 +29,15 @@
 
 /**
  * \defgroup tcp TCP helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/libnetfilter_queue_tcp.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -91,6 +100,17 @@ unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb)
  * \defgroup tcp_internals Internal TCP functions
  *
  * Most user-space programs will never need these.
+ *
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <netinet/ip.h>
+#include <netinet/ip6.h>
+#include <netinet/tcp.h>
+#include <libnetfilter_queue/libnetfilter_queue_tcp.h>
+\endmanonly
  *
  * @{
  */
diff --git a/src/extra/udp.c b/src/extra/udp.c
index ff91311..ede2196 100644
--- a/src/extra/udp.c
+++ b/src/extra/udp.c
@@ -28,6 +28,15 @@
 
 /**
  * \defgroup udp UDP helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libmnl/libmnl.h>
+#include <libnetfilter_queue/libnetfilter_queue_udp.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -91,6 +100,17 @@ unsigned int nfq_udp_get_payload_len(struct udphdr *udph, struct pkt_buff *pktb)
  * \defgroup udp_internals Internal UDP functions
  *
  * Most user-space programs will never need these.
+ *
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <netinet/ip.h>
+#include <netinet/ip6.h>
+#include <netinet/udp.h>
+#include <libnetfilter_queue/libnetfilter_queue_udp.h>
+\endmanonly
  *
  * @{
  */
diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index 11a4e7c..a170143 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -271,7 +271,7 @@ struct nfnl_handle *nfq_nfnlh(struct nfq_handle *h)
 		nfq_handle_packet(h, buf, rv);
 	}
 \endverbatim
- * When the decision on a packet has been choosed, the verdict has to be given
+ * When the decision on a packet has been chosen, the verdict has to be given
  * by calling nfq_set_verdict() or nfq_set_verdict2(). The verdict
  * determines the destiny of the packet as follows:
  *
@@ -288,8 +288,18 @@ struct nfnl_handle *nfq_nfnlh(struct nfq_handle *h)
  * is to also set an nfmark using nfq_set_verdict2, and set up the nefilter
  * rules to only queue a packet when the mark is not (yet) set.
  *
- * Data and information about the packet can be fetch by using message parsing
+ * Data and information about the packet can be fetched by using message parsing
  * functions (See \link Parsing \endlink).
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter.h>
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -437,6 +447,14 @@ out_free:
  *
  * When the program has finished with libnetfilter_queue, it has to call
  * the nfq_close() function to free all associated resources.
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
  *
  * @{
  */
@@ -950,6 +968,15 @@ int nfq_set_verdict_mark(struct nfq_q_handle *qh, uint32_t id,
 
 /**
  * \defgroup Parsing Message parsing functions [DEPRECATED]
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -1349,6 +1376,15 @@ do {								\
 
 /**
  * \defgroup Printing Printing [DEPRECATED]
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
diff --git a/src/nlmsg.c b/src/nlmsg.c
index e141156..b1154fc 100644
--- a/src/nlmsg.c
+++ b/src/nlmsg.c
@@ -27,6 +27,16 @@
 
 /**
  * \defgroup nfq_verd Verdict helpers
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter.h>
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -139,6 +149,15 @@ void nfq_nlmsg_verdict_put_pkt(struct nlmsghdr *nlh, const void *pkt,
 
 /**
  * \defgroup nfq_cfg Config helpers
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
@@ -205,6 +224,15 @@ void nfq_nlmsg_cfg_put_qmaxlen(struct nlmsghdr *nlh, uint32_t queue_maxlen)
 
 /**
  * \defgroup nlmsg Netlink message helper functions
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <linux/netfilter/nfnetlink_queue.h>
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
+ *
  * @{
  */
 
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 1/1] src: doc: Insert SYNOPSIS sections for man pages

[Pablo Neira Ayuso]

On Fri, Aug 13, 2021 at 02:44:36PM +1000, Duncan Roe wrote:
> In order to work with the post-processing logic in doxygen/Makefile.am,
> SYNOPSIS sections must be inserted at the end of the module description
> (text after \defgroup or \addtogroup)
> (becomes Detailed Description in the man page).

Applied, thanks.