Document netconn API in doxygen module style

src/api/api_lib.c

@@ -1,7 +1,6 @@
 /**
  * @file
  * Sequential API External module
- *
  */
 
 /*
@@ -33,7 +32,29 @@
  * This file is part of the lwIP TCP/IP stack.
  *
  * Author: Adam Dunkels <adam@sics.se>
- *
+ */
+
+/**
+ * @defgroup netconn Netconn API
+ * Thread-safe, to be called from non-TCPIP threads only.
+ * TX/RX handling based on @ref netbuf (containing @ref pbuf)
+ * to avoid copying data around.
+ * 
+ * @defgroup netconn_common Common functions
+ * @ingroup netconn
+ * For use with TCP and UDP
+ * 
+ * @defgroup netconn_tcp TCP only
+ * @ingroup netconn
+ * TCP only functions
+ * 
+ * @defgroup netconn_udp UDP only
+ * @ingroup netconn
+ * UDP only functions
+ * 
+ * @defgroup netconn_dns DNS
+ * @ingroup netconn
+ * DNS lookup
  */
 
 /* This is the part of the API that is linked with
@@ -94,6 +115,7 @@ netconn_apimsg(tcpip_callback_fn fn, struct api_msg *apimsg)
 }
 
 /**
+ * @ingroup netconn_common
  * Create a new netconn (of a specific type) that has a callback function.
  * The corresponding pcb is also created.
  *
@@ -138,6 +160,7 @@ netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, netconn_cal
 }
 
 /**
+ * @ingroup netconn_common
  * Close a netconn 'connection' and free its resources.
  * UDP and RAW connection are completely closed, TCP pcbs might still be in a waitstate
  * after this returns.
@@ -181,6 +204,7 @@ netconn_delete(struct netconn *conn)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Get the local or remote IP address and port of a netconn.
  * For RAW netconns, this returns the protocol instead of a port!
  *
@@ -219,6 +243,7 @@ netconn_getaddr(struct netconn *conn, ip_addr_t *addr, u16_t *port, u8_t local)
 }
 
 /**
+ * @ingroup netconn_common
  * Bind a netconn to a specific local IP address and port.
  * Binding one netconn twice might not always be checked correctly!
  *
@@ -252,6 +277,7 @@ netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port)
 }
 
 /**
+ * @ingroup netconn_common
  * Connect a netconn to a specific remote IP address and port.
  *
  * @param conn the netconn to connect
@@ -283,6 +309,7 @@ netconn_connect(struct netconn *conn, const ip_addr_t *addr, u16_t port)
 }
 
 /**
+ * @ingroup netconn_udp
  * Disconnect a netconn from its current peer (only valid for UDP netconns).
  *
  * @param conn the netconn to disconnect
@@ -305,6 +332,7 @@ netconn_disconnect(struct netconn *conn)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Set a TCP netconn into listen mode
  *
  * @param conn the tcp netconn to set to listen mode
@@ -341,6 +369,7 @@ netconn_listen_with_backlog(struct netconn *conn, u8_t backlog)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Accept a new connection on a TCP listening netconn.
  *
  * @param conn the TCP listen netconn
@@ -429,6 +458,7 @@ netconn_accept(struct netconn *conn, struct netconn **new_conn)
 }
 
 /**
+ * @ingroup netconn_common
  * Receive data: actual implementation that doesn't care whether pbuf or netbuf
  * is received
  *
@@ -553,6 +583,7 @@ netconn_recv_data(struct netconn *conn, void **new_buf)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Receive data (in form of a pbuf) from a TCP netconn
  *
  * @param conn the netconn from which to receive data
@@ -571,6 +602,7 @@ netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf)
 }
 
 /**
+ * @ingroup netconn_common
  * Receive data (in form of a netbuf containing a packet buffer) from a netconn
  *
  * @param conn the netconn from which to receive data
@@ -630,6 +662,7 @@ netconn_recv(struct netconn *conn, struct netbuf **new_buf)
 }
 
 /**
+ * @ingroup netconn_udp
  * Send data (in form of a netbuf) to a specific remote IP address and port.
  * Only to be used for UDP and RAW netconns (not TCP).
  *
@@ -651,6 +684,7 @@ netconn_sendto(struct netconn *conn, struct netbuf *buf, const ip_addr_t *addr,
 }
 
 /**
+ * @ingroup netconn_udp
  * Send data over a UDP or RAW netconn (that is already connected).
  *
  * @param conn the UDP or RAW netconn over which to send data
@@ -676,6 +710,7 @@ netconn_send(struct netconn *conn, struct netbuf *buf)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Send data over a TCP netconn.
  *
  * @param conn the TCP netconn over which to send data
@@ -747,6 +782,7 @@ netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size,
 }
 
 /**
+ * @ingroup netconn_tcp
  * Close or shutdown a TCP netconn (doesn't delete it).
  *
  * @param conn the TCP netconn to close or shutdown
@@ -783,6 +819,7 @@ netconn_close_shutdown(struct netconn *conn, u8_t how)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Close a TCP netconn (doesn't delete it).
  *
  * @param conn the TCP netconn to close
@@ -796,6 +833,7 @@ netconn_close(struct netconn *conn)
 }
 
 /**
+ * @ingroup netconn_tcp
  * Shut down one or both sides of a TCP netconn (doesn't delete it).
  *
  * @param conn the TCP netconn to shut down
@@ -811,6 +849,7 @@ netconn_shutdown(struct netconn *conn, u8_t shut_rx, u8_t shut_tx)
 
 #if LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD)
 /**
+ * @ingroup netconn_udp
  * Join multicast groups for UDP netconns.
  *
  * @param conn the UDP netconn for which to change multicast addresses
@@ -854,6 +893,7 @@ netconn_join_leave_group(struct netconn *conn,
 
 #if LWIP_DNS
 /**
+ * @ingroup netconn_dns
  * Execute a DNS query, only one IP address is returned
  *
  * @param name a string representation of the DNS host name to query

src/api/netbuf.c

@@ -36,6 +36,13 @@
  *
  */
 
+/**
+ * @defgroup netbuf Network buffers
+ * @ingroup netconn
+ * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally
+ * to avoid copying data around.
+ */
+
 #include "lwip/opt.h"
 
 #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */
@@ -46,6 +53,7 @@
 #include <string.h>
 
 /**
+ * @ingroup netbuf
  * Create (allocate) and initialize a new netbuf.
  * The netbuf doesn't yet contain a packet buffer!
  *
@@ -79,6 +87,7 @@ netbuf *netbuf_new(void)
 }
 
 /**
+ * @ingroup netbuf
  * Deallocate a netbuf allocated by netbuf_new().
  *
  * @param buf pointer to a netbuf allocated by netbuf_new()
@@ -96,6 +105,7 @@ netbuf_delete(struct netbuf *buf)
 }
 
 /**
+ * @ingroup netbuf
  * Allocate memory for a packet buffer for a given netbuf.
  *
  * @param buf the netbuf for which to allocate a packet buffer
@@ -123,6 +133,7 @@ netbuf_alloc(struct netbuf *buf, u16_t size)
 }
 
 /**
+ * @ingroup netbuf
  * Free the packet buffer included in a netbuf
  *
  * @param buf pointer to the netbuf which contains the packet buffer to free
@@ -138,6 +149,7 @@ netbuf_free(struct netbuf *buf)
 }
 
 /**
+ * @ingroup netbuf
  * Let a netbuf reference existing (non-volatile) data.
  *
  * @param buf netbuf which should reference the data
@@ -165,6 +177,7 @@ netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size)
 }
 
 /**
+ * @ingroup netbuf
  * Chain one netbuf to another (@see pbuf_chain)
  *
  * @param head the first netbuf
@@ -181,6 +194,7 @@ netbuf_chain(struct netbuf *head, struct netbuf *tail)
 }
 
 /**
+ * @ingroup netbuf
  * Get the data pointer and length of the data inside a netbuf.
  *
  * @param buf netbuf to get the data from
@@ -205,6 +219,7 @@ netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len)
 }
 
 /**
+ * @ingroup netbuf
  * Move the current data pointer of a packet buffer contained in a netbuf
  * to the next part.
  * The packet buffer itself is not modified.
@@ -229,6 +244,7 @@ netbuf_next(struct netbuf *buf)
 }
 
 /**
+ * @ingroup netbuf
  * Move the current data pointer of a packet buffer contained in a netbuf
  * to the beginning of the packet.
  * The packet buffer itself is not modified.

src/core/netif.c

@@ -35,7 +35,7 @@
  */
 
 /**
- * @defgroup netif Network interface
+ * @defgroup netif Network interface (NETIF)
  */
 
 #include "lwip/opt.h"

src/core/pbuf.c

@@ -4,7 +4,7 @@
  */
 
 /**
- * @defgroup pbuf PBUF
+ * @defgroup pbuf Payload buffers (PBUF)
  *
  * Packets are built from the pbuf data structure. It supports dynamic
  * memory allocation for packet contents or can reference externally

src/include/lwip/api.h

@@ -81,7 +81,7 @@ extern "C" {
 #endif /* LWIP_IPV6 */
 
 
-    /* Helpers to process several netconn_types by the same code */
+/* Helpers to process several netconn_types by the same code */
 #define NETCONNTYPE_GROUP(t)         ((t)&0xF0)
 #define NETCONNTYPE_DATAGRAM(t)      ((t)&0xE0)
 #if LWIP_IPV6
@@ -94,7 +94,9 @@ extern "C" {
 #define NETCONNTYPE_ISUDPNOCHKSUM(t) ((t) == NETCONN_UDPNOCHKSUM)
 #endif /* LWIP_IPV6 */
 
-/** Protocol family and type of the netconn */
+/** @ingroup netconn_common
+ * Protocol family and type of the netconn
+ */
 enum netconn_type {
   NETCONN_INVALID     = 0,
   /* NETCONN_TCP Group */
@@ -252,7 +254,10 @@ struct netconn {
 }} while(0);
 
 /* Network connection functions: */
+
+/** @ingroup netconn_common */
 #define netconn_new(t)                  netconn_new_with_proto_and_callback(t, 0, NULL)
+/** @ingroup netconn_common */
 #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c)
 struct netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto,
                                              netconn_callback callback);
@@ -262,7 +267,9 @@ err_t   netconn_delete(struct netconn *conn);
 
 err_t   netconn_getaddr(struct netconn *conn, ip_addr_t *addr,
                         u16_t *port, u8_t local);
+/** @ingroup netconn_common */
 #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0)
+/** @ingroup netconn_common */
 #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1)
 
 err_t   netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port);
@@ -278,6 +285,7 @@ err_t   netconn_sendto(struct netconn *conn, struct netbuf *buf,
 err_t   netconn_send(struct netconn *conn, struct netbuf *buf);
 err_t   netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size,
                              u8_t apiflags, size_t *bytes_written);
+/** @ingroup netconn_tcp */
 #define netconn_write(conn, dataptr, size, apiflags) \
           netconn_write_partly(conn, dataptr, size, apiflags, NULL)
 err_t   netconn_close(struct netconn *conn);