Document DNS, memory pools and PBUFs as modules

doc/doxygen/main_page.h

@@ -47,7 +47,7 @@
  *   http://lists.nongnu.org/archive/html/lwip-devel/\n
  * \n
  * Continuous integration builds (GCC, clang):\n
- *   https://travis-ci.org/yarrick/lwip-merged
+ *   https://travis-ci.org/yarrick/lwip-merged\n
  * \n
  * lwIP was originally written by Adam Dunkels:\n
  *   http://dunkels.com/adam/\n

src/core/dns.c

@@ -1,18 +1,14 @@
 /**
  * @file
  * DNS - host name to IP address resolver.
- *
  */
 
-/**
+/*
-
- * This file implements a DNS host name to IP address resolver.
-
  * Port to lwIP from uIP
  * by Jim Pettinato April 2007
-
+ *
  * security fixes and more by Simon Goldschmidt
-
+ *
  * uIP version Copyright (c) 2002-2003, Adam Dunkels.
  * All rights reserved.
  *
@@ -39,9 +35,12 @@
  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @defgroup dns DNS
  *
- *
+ * Implements a DNS host name to IP address resolver.
- * DNS.C
  *
  * The lwIP DNS resolver functions are used to lookup a host name and
  * map it to a numerical IP address. It maintains a list of resolved
@@ -59,6 +58,8 @@
  * Once a hostname has been resolved (or found to be non-existent),
  * the resolver code calls a specified callback function (which
  * must be implemented by the module that uses the resolver).
+ * 
+ * All functions must be called from TCPIP thread.
  */
 
 /*-----------------------------------------------------------------------------
@@ -408,6 +409,7 @@ dns_init(void)
 }
 
 /**
+ * @ingroup dns
  * Initialize one of the DNS servers.
  *
  * @param numdns the index of the DNS server to set must be < DNS_MAX_SERVERS
@@ -426,6 +428,7 @@ dns_setserver(u8_t numdns, const ip_addr_t *dnsserver)
 }
 
 /**
+ * @ingroup dns
  * Obtain one of the currently configured DNS server.
  *
  * @param numdns the index of the DNS server
@@ -484,6 +487,7 @@ dns_init_local(void)
 }
 
 /**
+ * @ingroup dns
  * Scans the local host-list for a hostname.
  *
  * @param hostname Hostname to look for in the local host-list
@@ -522,7 +526,9 @@ dns_lookup_local(const char *hostname, ip_addr_t *addr LWIP_DNS_ADDRTYPE_ARG(u8_
 }
 
 #if DNS_LOCAL_HOSTLIST_IS_DYNAMIC
-/** Remove all entries from the local host-list for a specific hostname
+/**
+ * @ingroup dns
+ * Remove all entries from the local host-list for a specific hostname
  * and/or IP address
  *
  * @param hostname hostname for which entries shall be removed from the local
@@ -558,6 +564,7 @@ dns_local_removehost(const char *hostname, const ip_addr_t *addr)
 }
 
 /**
+ * @ingroup dns
  * Add a hostname/IP address pair to the local host-list.
  * Duplicates are not checked.
  *
@@ -591,6 +598,7 @@ dns_local_addhost(const char *hostname, const ip_addr_t *addr)
 #endif /* DNS_LOCAL_HOSTLIST */
 
 /**
+ * @ingroup dns
  * Look up a hostname in the array of known hostnames.
  *
  * @note This function only looks in the internal array of known
@@ -1378,6 +1386,7 @@ dns_enqueue(const char *name, size_t hostnamelen, dns_found_callback found,
 }
 
 /**
+ * @ingroup dns
  * Resolve a hostname (string) into an IP address.
  * NON-BLOCKING callback version for use with raw API!!!
  *
@@ -1403,7 +1412,9 @@ dns_gethostbyname(const char *hostname, ip_addr_t *addr, dns_found_callback foun
   return dns_gethostbyname_addrtype(hostname, addr, found, callback_arg, LWIP_DNS_ADDRTYPE_DEFAULT);
 }
 
-/** Like dns_gethostbyname, but returned address type can be controlled:
+/**
+ * @ingroup dns
+ * Like dns_gethostbyname, but returned address type can be controlled:
  * @param hostname the hostname that is to be queried
  * @param addr pointer to a ip_addr_t where to store the address if it is already
  *             cached in the dns_table (only valid if ERR_OK is returned!)

src/core/memp.c

@@ -38,6 +38,10 @@
  *
  */
 
+/**
+ * @defgroup mempool Memory pools
+ */
+
 #include "lwip/opt.h"
 
 #include "lwip/memp.h"

src/core/pbuf.c

@@ -1,6 +1,10 @@
 /**
  * @file
  * Packet buffer management
+ */
+
+/**
+ * @defgroup pbuf PBUF
  *
  * Packets are built from the pbuf data structure. It supports dynamic
  * memory allocation for packet contents or can reference externally
@@ -165,6 +169,7 @@ pbuf_pool_is_empty(void)
 #endif /* !LWIP_TCP || !TCP_QUEUE_OOSEQ || !PBUF_POOL_FREE_OOSEQ */
 
 /**
+ * @ingroup pbuf
  * Allocates a pbuf of the given type (possibly a chain for PBUF_POOL type).
  *
  * The actual memory allocated for the pbuf is determined by the
@@ -346,7 +351,9 @@ pbuf_alloc(pbuf_layer layer, u16_t length, pbuf_type type)
 }
 
 #if LWIP_SUPPORT_CUSTOM_PBUF
-/** Initialize a custom pbuf (already allocated).
+/**
+ * @ingroup pbuf
+ * Initialize a custom pbuf (already allocated).
  *
  * @param l flag to define header size
  * @param length size of the pbuf's payload
@@ -413,6 +420,7 @@ pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type, struct pbuf_cust
 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
 
 /**
+ * @ingroup pbuf
  * Shrink a pbuf chain to a desired length.
  *
  * @param p pbuf to shrink.
@@ -616,6 +624,7 @@ pbuf_header_force(struct pbuf *p, s16_t header_size_increment)
 }
 
 /**
+ * @ingroup pbuf
  * Dereference a pbuf chain or queue and deallocate any no-longer-used
  * pbufs at the head of this chain or queue.
  *
@@ -733,7 +742,6 @@ pbuf_free(struct pbuf *p)
  * @param p first pbuf of chain
  * @return the number of pbufs in a chain
  */
-
 u8_t
 pbuf_clen(struct pbuf *p)
 {
@@ -748,6 +756,7 @@ pbuf_clen(struct pbuf *p)
 }
 
 /**
+ * @ingroup pbuf
  * Increment the reference count of the pbuf.
  *
  * @param p pbuf to increase reference counter of
@@ -766,6 +775,7 @@ pbuf_ref(struct pbuf *p)
 }
 
 /**
+ * @ingroup pbuf
  * Concatenate two pbufs (each may be a pbuf chain) and take over
  * the caller's reference of the tail pbuf.
  *
@@ -774,7 +784,6 @@ pbuf_ref(struct pbuf *p)
  *
  * @see pbuf_chain()
  */
-
 void
 pbuf_cat(struct pbuf *h, struct pbuf *t)
 {
@@ -801,6 +810,7 @@ pbuf_cat(struct pbuf *h, struct pbuf *t)
 }
 
 /**
+ * @ingroup pbuf
  * Chain two pbufs (or pbuf chains) together.
  *
  * The caller MUST call pbuf_free(t) once it has stopped
@@ -865,7 +875,7 @@ pbuf_dechain(struct pbuf *p)
 }
 
 /**
- *
+ * @ingroup pbuf
  * Create PBUF_RAM copies of pbufs.
  *
  * Used to queue packets on behalf of the lwIP stack, such as
@@ -938,6 +948,7 @@ pbuf_copy(struct pbuf *p_to, struct pbuf *p_from)
 }
 
 /**
+ * @ingroup pbuf
  * Copy (part of) the contents of a packet buffer
  * to an application supplied buffer.
  *
@@ -1037,6 +1048,7 @@ void pbuf_split_64k(struct pbuf *p, struct pbuf **rest)
 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
 
 /**
+ * @ingroup pbuf
  * Skip a number of bytes at the start of a pbuf
  *
  * @param in input pbuf
@@ -1062,6 +1074,7 @@ pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset)
 }
 
 /**
+ * @ingroup pbuf
  * Copy application supplied data into a pbuf.
  * This function can only be used to copy the equivalent of buf->tot_len data.
  *
@@ -1105,6 +1118,7 @@ pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len)
 }
 
 /**
+ * @ingroup pbuf
  * Same as pbuf_take() but puts data at an offset
  *
  * @param buf pbuf to fill with data
@@ -1138,6 +1152,7 @@ pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset)
 }
 
 /**
+ * @ingroup pbuf
  * Creates a single pbuf out of a queue of pbufs.
  *
  * @remark: Either the source pbuf 'p' is freed by this function or the original
@@ -1209,7 +1224,9 @@ pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
 }
 #endif /* LWIP_CHECKSUM_ON_COPY */
 
- /** Get one byte from the specified position in a pbuf
+/** 
+ * @ingroup pbuf
+ * Get one byte from the specified position in a pbuf
  * WARNING: returns zero for offset >= p->tot_len
  *
  * @param p pbuf to parse
@@ -1229,7 +1246,9 @@ pbuf_get_at(struct pbuf* p, u16_t offset)
   return 0;
 }
 
- /** Put one byte to the specified position in a pbuf
+/**
+ * @ingroup pbuf
+ * Put one byte to the specified position in a pbuf
  * WARNING: silently ignores offset >= p->tot_len
  *
  * @param p pbuf to fill
@@ -1248,7 +1267,9 @@ pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data)
   }
 }
 
-/** Compare pbuf contents at specified offset with memory s2, both of length n
+/**
+ * @ingroup pbuf
+ * Compare pbuf contents at specified offset with memory s2, both of length n
  *
  * @param p pbuf to compare
  * @param offset offset into p at which to start comparing
@@ -1283,7 +1304,9 @@ pbuf_memcmp(struct pbuf* p, u16_t offset, const void* s2, u16_t n)
   return 0xffff;
 }
 
-/** Find occurrence of mem (with length mem_len) in pbuf p, starting at offset
+/**
+ * @ingroup pbuf
+ * Find occurrence of mem (with length mem_len) in pbuf p, starting at offset
  * start_offset.
  *
  * @param p pbuf to search, maximum length is 0xFFFE since 0xFFFF is used as
@@ -1309,7 +1332,8 @@ pbuf_memfind(struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset)
   return 0xFFFF;
 }
 
-/** Find occurrence of substr with length substr_len in pbuf p, start at offset
+/**
+ * Find occurrence of substr with length substr_len in pbuf p, start at offset
  * start_offset
  * WARNING: in contrast to strstr(), this one does not stop at the first \0 in
  * the pbuf/source string!

src/core/tcp.c

@@ -135,7 +135,6 @@ static u8_t tcp_timer_ctr;
 static u16_t tcp_new_port(void);
 
 /**
- * @ingroup tcp_raw
  * Initialize this module.
  */
 void

src/core/udp.c

@@ -89,7 +89,6 @@ static u16_t udp_port = UDP_LOCAL_PORT_RANGE_START;
 struct udp_pcb *udp_pcbs;
 
 /**
- * @ingroup udp_raw
  * Initialize this module.
  */
 void

src/include/lwip/memp.h

@@ -70,12 +70,15 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
 
 #else /* MEMP_MEM_MALLOC */
 
-/** Declare a private memory pool 
+/** 
+ * @ingroup mempool
  * Declare prototype for private memory pool if it is used in multiple files
  */
 #define LWIP_MEMPOOL_PROTOTYPE(name) extern const struct memp_desc memp_ ## name
 
-/** Declare a private memory pool
+/**
+ * @ingroup mempool
+ * Declare a private memory pool
  * Private mempools example:
  * .h: only when pool is used in multiple .c files: LWIP_MEMPOOL_PROTOTYPE(my_private_pool);
  * .c:
@@ -105,11 +108,20 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
 
 #endif /* MEMP_MEM_MALLOC */
 
-/** Initialize a private memory pool */
+/**
+ * @ingroup mempool
+ * Initialize a private memory pool
+ */
 #define LWIP_MEMPOOL_INIT(name)    memp_init_pool(&memp_ ## name)
-/** Allocate from a private memory pool */
+/**
+ * @ingroup mempool
+ * Allocate from a private memory pool
+ */
 #define LWIP_MEMPOOL_ALLOC(name)   memp_malloc_pool(&memp_ ## name)
-/** Free element from a private memory pool */
+/**
+ * @ingroup mempool
+ * Free element from a private memory pool
+ */
 #define LWIP_MEMPOOL_FREE(name, x) memp_free_pool(&memp_ ## name, (x))
 
 #if MEM_USE_POOLS