src: doc: Insert SYNOPSIS sections for man pages

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>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

6 files changed, 110 insertions, 7 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
+ *
  * @{
  */
 
@@ -88,6 +97,15 @@ int nfq_ip_set_transport_header(struct pkt_buff *pktb, struct iphdr *iph)
  *
  * 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,21 +159,37 @@ 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
+ *
  * @{
  */
 
@@ -92,6 +101,17 @@ unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb)
  *
  * 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
+ *
  * @{
  */
 
@@ -92,6 +101,17 @@ unsigned int nfq_udp_get_payload_len(struct udphdr *udph, struct pkt_buff *pktb)
  *
  * 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
+ *
  * @{
  */