From bd7189f6fbe6648f5e61ca9aa1169ebaf846adde Mon Sep 17 00:00:00 2001 From: Duncan Roe Date: Fri, 13 Aug 2021 14:44:36 +1000 Subject: 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 Signed-off-by: Pablo Neira Ayuso --- 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(-) (limited to 'src') 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 +#include +\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 +#include +\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 +#include +\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 +#include +#include +#include +\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 +#include +\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 +#include +\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 +#include +\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 +#include +\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 +#include +#include +#include +\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 +#include +\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 +#include +#include +#include +\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 +#include +#include +\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 +#include +\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 +#include +\endmanonly + * * @{ */ @@ -1349,6 +1376,15 @@ do { \ /** * \defgroup Printing Printing [DEPRECATED] + * + * \manonly +.SH SYNOPSIS +.nf +\fB +#include +#include +\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 +#include +#include +\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 +#include +\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 +#include +\endmanonly + * * @{ */ -- cgit v1.2.1