src: doc: Final polish for current round

- Ensure all functions that return something have a \returns
- Demote more checksum functions to their own groups
  (reduces number of functions on main pages)
- Clarify wording where appropriate
- Add \sa (see also) where appropriate
- Fix documented function name for nfq_tcp_get_hdr
  (no other mismatches noticed, but there may be some)
- Add warnings regarding changing length of tcp packet
- Make group names unique within libnetfilter_queue
  (else man pages would be overwritten)

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

1 files changed, 14 insertions, 6 deletions

diff --git a/src/extra/udp.c b/src/extra/udp.c
index 9eee1c7..dc476d4 100644
--- a/src/extra/udp.c
+++ b/src/extra/udp.c
@@ -34,7 +34,10 @@
  * nfq_udp_get_hdr - get the UDP header.
  * \param pktb: Pointer to userspace network packet buffer
  *
- * \returns Pointer to the UDP header, or NULL if no valid UDP header is found.
+ * \returns validated pointer to the UDP header or NULL if the UDP header was
+ * not set or if a minimal length check fails.
+ * \note You have to call nfq_ip_set_transport_header() or
+ * nfq_ip6_set_transport_header() first to set the UDP header.
  */
 EXPORT_SYMBOL
 struct udphdr *nfq_udp_get_hdr(struct pkt_buff *pktb)
@@ -84,7 +87,7 @@ unsigned int nfq_udp_get_payload_len(struct udphdr *udph, struct pkt_buff *pktb)
 }
 
 /**
- * \defgroup internals Internal functions
+ * \defgroup udp_internals Internal UDP functions
  *
  * Most user-space programs will never need these.
  *
@@ -110,13 +113,14 @@ void nfq_udp_compute_checksum_ipv4(struct udphdr *udph, struct iphdr *iph)
 }
 
 /**
- * @}
- */
-
-/**
  * nfq_udp_compute_checksum_ipv6 - sets up the UDP checksum in a UDP/IPv6 packet
  * \param udph: pointer to the UDP header
  * \param ip6h: pointer to the IPv6 header
+ * \note
+ * nfq_udp_mangle_ipv6() invokes this function.
+ * As long as developers always use __nfq_udp_mangle_ipv6__ when changing the
+ * content of a UDP message, there is no need to call
+ * __nfq_udp_compute_checksum_ipv6__.
  */
 EXPORT_SYMBOL
 void nfq_udp_compute_checksum_ipv6(struct udphdr *udph, struct ip6_hdr *ip6h)
@@ -127,6 +131,10 @@ void nfq_udp_compute_checksum_ipv6(struct udphdr *udph, struct ip6_hdr *ip6h)
 }
 
 /**
+ * @}
+ */
+
+/**
  * nfq_udp_mangle_ipv4 - Mangle UDP/IPv4 packet buffer
  * \param pktb: Pointer to network packet buffer
  * \param match_offset: Offset from start of UDP data of content that you want