From 87855b0e0e8638e1b932f66cca016beedbbc2145 Mon Sep 17 00:00:00 2001
From: Dirk Ziegelmeier <dirk@ziegelmeier.net>
Date: Sat, 6 Aug 2016 20:28:49 +0200
Subject: [PATCH] Update doxgen docs: PBUF layers, IPv4 and IPv6 functions, add
 some missing tcp raw API functions

---
 src/core/ipv4/ip4.c     |  6 ++++++
 src/core/ipv6/ip6.c     |  5 +++++
 src/core/tcp_out.c      |  7 ++++++-
 src/include/lwip/pbuf.h | 22 ++++++++++++++++++++++
 4 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/src/core/ipv4/ip4.c b/src/core/ipv4/ip4.c
index 0dba2dc2..9fa9b566 100644
--- a/src/core/ipv4/ip4.c
+++ b/src/core/ipv4/ip4.c
@@ -134,6 +134,7 @@ ip4_route_src(const ip4_addr_t *dest, const ip4_addr_t *src)
 #endif /* LWIP_HOOK_IP4_ROUTE_SRC */
 
 /**
+ * @ingroup ip4
  * Finds the appropriate network interface for a given IP address. It
  * searches the list of network interfaces linearly. A match is found
  * if the masked IP address of the network interface equals the masked
@@ -712,6 +713,7 @@ ip4_input(struct pbuf *p, struct netif *inp)
 }
 
 /**
+ * @ingroup ip4
  * Sends an IP packet on a network interface. This function constructs
  * the IP header and calculates the IP header checksum. If the source
  * IP address is NULL, the IP address of the outgoing network
@@ -746,6 +748,7 @@ ip4_output_if(struct pbuf *p, const ip4_addr_t *src, const ip4_addr_t *dest,
 }
 
 /**
+ * @ingroup ip4
  * Same as ip_output_if() but with the possibility to include IP options:
  *
  * @ param ip_options pointer to the IP options, copied into the IP header
@@ -773,6 +776,7 @@ ip4_output_if_opt(struct pbuf *p, const ip4_addr_t *src, const ip4_addr_t *dest,
 }
 
 /**
+ * @ingroup ip4
  * Same as ip_output_if() but 'src' address is not replaced by netif address
  * when it is 'any'.
  */
@@ -786,6 +790,7 @@ ip4_output_if_src(struct pbuf *p, const ip4_addr_t *src, const ip4_addr_t *dest,
 }
 
 /**
+ * @ingroup ip4
  * Same as ip_output_if_opt() but 'src' address is not replaced by netif address
  * when it is 'any'.
  */
@@ -947,6 +952,7 @@ ip4_output_if_opt_src(struct pbuf *p, const ip4_addr_t *src, const ip4_addr_t *d
 }
 
 /**
+ * @ingroup ip4
  * Simple interface to ip_output_if. It finds the outgoing network
  * interface and calls upon ip_output_if to do the actual work.
  *
diff --git a/src/core/ipv6/ip6.c b/src/core/ipv6/ip6.c
index 650e5af7..bddf9f4f 100644
--- a/src/core/ipv6/ip6.c
+++ b/src/core/ipv6/ip6.c
@@ -60,6 +60,7 @@
 #include "lwip/stats.h"
 
 /**
+ * @ingroup ip6
  * Finds the appropriate network interface for a given IPv6 address. It tries to select
  * a netif following a sequence of heuristics:
  * 1) if there is only 1 netif, return it
@@ -192,6 +193,7 @@ ip6_route(const ip6_addr_t *src, const ip6_addr_t *dest)
 }
 
 /**
+ * @ingroup ip6
  * Select the best IPv6 source address for a given destination
  * IPv6 address. Loosely follows RFC 3484. "Strong host" behavior
  * is assumed.
@@ -776,6 +778,7 @@ ip6_input_cleanup:
 
 
 /**
+ * @igroup ip6
  * Sends an IPv6 packet on a network interface. This function constructs
  * the IPv6 header. If the source IPv6 address is NULL, the IPv6 "ANY" address is
  * used as source (usually during network startup). If the source IPv6 address it
@@ -820,6 +823,7 @@ ip6_output_if(struct pbuf *p, const ip6_addr_t *src, const ip6_addr_t *dest,
 }
 
 /**
+ * @ingroup ip6
  * Same as ip6_output_if() but 'src' address is not replaced by netif address
  * when it is 'any'.
  */
@@ -903,6 +907,7 @@ ip6_output_if_src(struct pbuf *p, const ip6_addr_t *src, const ip6_addr_t *dest,
 }
 
 /**
+ * @ingroup ip6
  * Simple interface to ip6_output_if. It finds the outgoing network
  * interface and calls upon ip6_output_if to do the actual work.
  *
diff --git a/src/core/tcp_out.c b/src/core/tcp_out.c
index 30289791..4808f247 100644
--- a/src/core/tcp_out.c
+++ b/src/core/tcp_out.c
@@ -350,6 +350,7 @@ tcp_write_checks(struct tcp_pcb *pcb, u16_t len)
 }
 
 /**
+ * @ingroup tcp_raw
  * Write data for sending (but does not send it immediately).
  *
  * It waits in the expectation of more data being sent soon (as
@@ -874,7 +875,9 @@ tcp_build_wnd_scale_option(u32_t *opts)
 }
 #endif
 
-/** Send an ACK without data.
+/**
+ * @ingroup tcp_raw
+ * Send an ACK without data.
  *
  * @param pcb Protocol control block for the TCP connection to send the ACK
  */
@@ -946,6 +949,7 @@ tcp_send_empty_ack(struct tcp_pcb *pcb)
 }
 
 /**
+ * @ingroup tcp_raw
  * Find out what we can send and send it
  *
  * @param pcb Protocol control block for the TCP connection to send data
@@ -1465,6 +1469,7 @@ tcp_rexmit_fast(struct tcp_pcb *pcb)
 
 
 /**
+ * @ingroup tcp_raw
  * Send keepalive packets to keep a connection active although
  * no data is sent over it.
  *
diff --git a/src/include/lwip/pbuf.h b/src/include/lwip/pbuf.h
index a3a761f5..32b75626 100644
--- a/src/include/lwip/pbuf.h
+++ b/src/include/lwip/pbuf.h
@@ -65,11 +65,33 @@ extern "C" {
 #define PBUF_IP_HLEN        20
 #endif
 
+/**
+ * @ingroup pbuf
+ * Enumeration of pbuf layers
+ */
 typedef enum {
+  /** Includes spare room for transport layer header, e.g. TCP header.
+   * Use this if you intend to pass the pbuf to functions like udp_send(),
+   * tcp_write(), netconn_send() or netconn_write().
+   */
   PBUF_TRANSPORT,
+  /** Includes spare room for IP header.
+   * Use this if you intend to pass the pbuf to functions like raw_send().
+   */
   PBUF_IP,
+  /** Includes spare room for link layer header (ethernet header).
+   * Use this if you intend to pass the pbuf to functions like ip4_output(),
+   * ip6_output() or ip_output().
+   */
   PBUF_LINK,
+  /** Includes spare room for additional encapsulation header before ethernet headers (e.g. 802.11).
+   * Use this if you intend to pass the pbuf to functions like netif->linkoutput()
+   */
   PBUF_RAW_TX,
+  /** No spare room, final packet for sending.
+   * Use this if you intend to pass the pbuf to functions like netif->linkoutput()
+   * or for input packets received by ethernet-layer netif drivers.
+   */
   PBUF_RAW
 } pbuf_layer;