Some documentation updates

doc/doxygen/lwip.Doxyfile

@@ -842,8 +842,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../../src/include/netif/ppp/polarssl \
-                         ../../src/include/lwip/priv
+EXCLUDE                = ../../src/include/netif/ppp/polarssl
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

src/include/lwip/ip.h

@@ -80,7 +80,7 @@ extern "C" {
 #define IP_PCB_ADDRHINT
 #endif /* LWIP_NETIF_HWADDRHINT */
 
-/* This is the common part of all PCB types. It needs to be at the
+/** This is the common part of all PCB types. It needs to be at the
    beginning of a PCB type definition. It is located here so that
    changes to this common part are made in one location instead of
    having to change all PCB structs. */
@@ -112,7 +112,7 @@ struct ip_pcb {
 /* These flags are inherited (e.g. from a listen-pcb to a connection-pcb): */
 #define SOF_INHERITED   (SOF_REUSEADDR|SOF_KEEPALIVE)
 
-/* Global variables of this module, kept in a struct for efficient access using base+index. */
+/** Global variables of this module, kept in a struct for efficient access using base+index. */
 struct ip_globals
 {
   /** The interface that accepted the packet for the current callback invocation. */

src/include/lwip/ip4_addr.h

@@ -46,13 +46,13 @@
 extern "C" {
 #endif
 
-/* This is the aligned version of ip4_addr_t,
+/** This is the aligned version of ip4_addr_t,
    used as local variable, on the stack, etc. */
 struct ip4_addr {
   u32_t addr;
 };
 
-/* This is the packed version of ip4_addr_t,
+/** This is the packed version of ip4_addr_t,
    used in network headers that are itself packed */
 #ifdef PACK_STRUCT_USE_INCLUDES
 #  include "arch/bpstruct.h"
@@ -71,7 +71,7 @@ PACK_STRUCT_END
 typedef struct ip4_addr ip4_addr_t;
 typedef struct ip4_addr_packed ip4_addr_p_t;
 
-/*
+/**
  * struct ipaddr2 is used in the definition of the ARP packet format in
  * order to support compilers that don't have structure packing.
  */

src/include/lwip/ip6.h

@@ -70,21 +70,21 @@ extern "C" {
 #define IP6_NEXTH_UDPLITE   136
 
 
-/* The IPv6 header. */
+/** The IPv6 header. */
 #ifdef PACK_STRUCT_USE_INCLUDES
 #  include "arch/bpstruct.h"
 #endif
 PACK_STRUCT_BEGIN
 struct ip6_hdr {
-  /* version / traffic class / flow label */
+  /** version / traffic class / flow label */
   PACK_STRUCT_FIELD(u32_t _v_tc_fl);
-  /* payload length */
+  /** payload length */
   PACK_STRUCT_FIELD(u16_t _plen);
-  /* next header */
+  /** next header */
   PACK_STRUCT_FLD_8(u8_t _nexth);
-  /* hop limit */
+  /** hop limit */
   PACK_STRUCT_FLD_8(u8_t _hoplim);
-  /* source and destination IP addresses */
+  /** source and destination IP addresses */
   PACK_STRUCT_FLD_S(ip6_addr_p_t src);
   PACK_STRUCT_FLD_S(ip6_addr_p_t dest);
 } PACK_STRUCT_STRUCT;

src/include/lwip/ip6_frag.h

@@ -61,7 +61,7 @@ extern "C" {
 #define IPV6_FRAG_COPYHEADER   0
 #endif
 
-/* The IPv6 reassembly timer interval in milliseconds. */
+/** The IPv6 reassembly timer interval in milliseconds. */
 #define IP6_REASS_TMR_INTERVAL 1000
 
 /* Copy the complete header of the first fragment to struct ip6_reassdata
@@ -74,7 +74,7 @@ extern "C" {
 #define IPV6_FRAG_HDRREF(hdr) (hdr)
 #endif /* IPV6_FRAG_COPYHEADER */
 
-/* IPv6 reassembly helper struct.
+/** IPv6 reassembly helper struct.
  * This is exported because memp needs to know the size.
  */
 struct ip6_reassdata {
@@ -95,11 +95,11 @@ struct pbuf * ip6_reass(struct pbuf *p);
 
 #if LWIP_IPV6 && LWIP_IPV6_FRAG  /* don't build if not configured for use in lwipopts.h */
 
+#ifndef LWIP_PBUF_CUSTOM_REF_DEFINED
+#define LWIP_PBUF_CUSTOM_REF_DEFINED
 /** A custom pbuf that holds a reference to another pbuf, which is freed
  * when this custom pbuf is freed. This is used to create a custom PBUF_REF
  * that points into the original pbuf. */
-#ifndef LWIP_PBUF_CUSTOM_REF_DEFINED
-#define LWIP_PBUF_CUSTOM_REF_DEFINED
 struct pbuf_custom_ref {
   /** 'base class' */
   struct pbuf_custom pc;

src/include/lwip/ip_addr.h

@@ -83,8 +83,9 @@ extern const ip_addr_t ip_addr_any_type;
 #define IP_ADDR_PCB_VERSION_MATCH_EXACT(pcb, ipaddr) (IP_GET_TYPE(&pcb->local_ip) == IP_GET_TYPE(ipaddr))
 #define IP_ADDR_PCB_VERSION_MATCH(pcb, ipaddr) (IP_IS_ANY_TYPE_VAL(pcb->local_ip) || IP_ADDR_PCB_VERSION_MATCH_EXACT(pcb, ipaddr))
 
-/* Convert generic ip address to specific protocol version */
+/** Convert generic ip address to specific protocol version */
 #define ip_2_ip6(ipaddr)   (&((ipaddr)->u_addr.ip6))
+/** Convert generic ip address to specific protocol version */
 #define ip_2_ip4(ipaddr)   (&((ipaddr)->u_addr.ip4))
 
 #define IP_ADDR4(ipaddr,a,b,c,d)      do { IP4_ADDR(ip_2_ip4(ipaddr),a,b,c,d); \

src/include/lwip/ip_frag.h

@@ -55,7 +55,7 @@ extern "C" {
 /* The IP reassembly timer interval in milliseconds. */
 #define IP_TMR_INTERVAL 1000
 
-/* IP reassembly helper struct.
+/** IP reassembly helper struct.
  * This is exported because memp needs to know the size.
  */
 struct ip_reassdata {
@@ -74,11 +74,11 @@ struct pbuf * ip4_reass(struct pbuf *p);
 
 #if IP_FRAG
 #if !IP_FRAG_USES_STATIC_BUF && !LWIP_NETIF_TX_SINGLE_PBUF
+#ifndef LWIP_PBUF_CUSTOM_REF_DEFINED
+#define LWIP_PBUF_CUSTOM_REF_DEFINED
 /** A custom pbuf that holds a reference to another pbuf, which is freed
  * when this custom pbuf is freed. This is used to create a custom PBUF_REF
  * that points into the original pbuf. */
-#ifndef LWIP_PBUF_CUSTOM_REF_DEFINED
-#define LWIP_PBUF_CUSTOM_REF_DEFINED
 struct pbuf_custom_ref {
   /** 'base class' */
   struct pbuf_custom pc;

src/include/lwip/memp.h

@@ -46,7 +46,7 @@ extern "C" {
 #define LWIP_MEMPOOL(name,num,size,desc)
 #include "lwip/priv/memp_std.h"
 
-/* Create the list of all memory pools managed by memp. MEMP_MAX represents a NULL pool at the end */
+/** Create the list of all memory pools managed by memp. MEMP_MAX represents a NULL pool at the end */
 typedef enum {
 #define LWIP_MEMPOOL(name,num,size,desc)  MEMP_##name,
 #include "lwip/priv/memp_std.h"
@@ -56,22 +56,8 @@ typedef enum {
 #include "lwip/priv/memp_priv.h"
 #include "lwip/stats.h"
 
-/* Private mempools example:
- * .h: only when pool is used in multiple .c files: LWIP_MEMPOOL_PROTOTYPE(my_private_pool);
- * .c:
- *   - in global variables section: LWIP_MEMPOOL_DECLARE(my_private_pool, 10, sizeof(foo), "Some description")
- *   - call ONCE before using pool (e.g. in some init() function): LWIP_MEMPOOL_INIT(my_private_pool);
- *   - allocate: void* my_new_mem = LWIP_MEMPOOL_ALLOC(my_private_pool);
- *   - free: LWIP_MEMPOOL_FREE(my_private_pool, my_new_mem);
- *
- * To relocate a pool, declare it as extern in cc.h. Example for GCC:
- *   extern u8_t __attribute__((section(".onchip_mem"))) memp_memory_my_private_pool[];
- */
-
 extern const struct memp_desc* const memp_pools[MEMP_MAX];
 
-#define LWIP_MEMPOOL_PROTOTYPE(name) extern const struct memp_desc memp_ ## name
-
 #if MEMP_MEM_MALLOC
 
 #include "lwip/mem.h"
@@ -91,6 +77,23 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
 
 #else /* MEMP_MEM_MALLOC */
 
+/** Declare a private memory pool 
+ * 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
+ * Private mempools example:
+ * .h: only when pool is used in multiple .c files: LWIP_MEMPOOL_PROTOTYPE(my_private_pool);
+ * .c:
+ *   - in global variables section: LWIP_MEMPOOL_DECLARE(my_private_pool, 10, sizeof(foo), "Some description")
+ *   - call ONCE before using pool (e.g. in some init() function): LWIP_MEMPOOL_INIT(my_private_pool);
+ *   - allocate: void* my_new_mem = LWIP_MEMPOOL_ALLOC(my_private_pool);
+ *   - free: LWIP_MEMPOOL_FREE(my_private_pool, my_new_mem);
+ *
+ * To relocate a pool, declare it as extern in cc.h. Example for GCC:
+ *   extern u8_t __attribute__((section(".onchip_mem"))) memp_memory_my_private_pool[];
+ */
 #define LWIP_MEMPOOL_DECLARE(name,num,size,desc) \
   LWIP_DECLARE_MEMORY_ALIGNED(memp_memory_ ## name ## _base, ((num) * (MEMP_SIZE + MEMP_ALIGN_SIZE(size)))); \
     \
@@ -107,8 +110,11 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
     &memp_tab_ ## name \
   };
 
+/** Initialize a private memory pool */
 #define LWIP_MEMPOOL_INIT(name)    memp_init_pool(&memp_ ## name)
+/** Allocate from a private memory pool */
 #define LWIP_MEMPOOL_ALLOC(name)   memp_malloc_pool(&memp_ ## name)
+/** Free element from a private memory pool */
 #define LWIP_MEMPOOL_FREE(name, x) memp_free_pool(&memp_ ## name, (x))
 
 #if MEM_USE_POOLS

src/include/lwip/mld6.h

@@ -55,6 +55,7 @@
 extern "C" {
 #endif
 
+/** MLD group */
 struct mld_group {
   /** next link */
   struct mld_group *next;

src/include/lwip/nd6.h

@@ -58,7 +58,7 @@
 extern "C" {
 #endif
 
-/* Struct for tables. */
+/** Struct for tables. */
 struct nd6_neighbor_cache_entry {
   ip6_addr_t next_hop_address;
   struct netif * netif;

src/include/lwip/snmp.h

@@ -87,7 +87,7 @@ enum snmp_ifType {
   snmp_ifType_frame_relay
 };
 
-/* This macro has a precision of ~49 days because sys_now returns u32_t. #define your own if you want ~490 days. */
+/** This macro has a precision of ~49 days because sys_now returns u32_t. #define your own if you want ~490 days. */
 #ifndef MIB2_COPY_SYSUPTIME_TO
 #define MIB2_COPY_SYSUPTIME_TO(ptrToVal) (*(ptrToVal) = (sys_now() / 10))
 #endif

src/include/lwip/stats.h

@@ -60,6 +60,7 @@ extern "C" {
 #define STAT_COUNTER_F   U16_F
 #endif
 
+/** Protocol related stats */
 struct stats_proto {
   STAT_COUNTER xmit;             /* Transmitted packets. */
   STAT_COUNTER recv;             /* Received packets. */
@@ -75,6 +76,7 @@ struct stats_proto {
   STAT_COUNTER cachehit;
 };
 
+/** IGMP stats */
 struct stats_igmp {
   STAT_COUNTER xmit;             /* Transmitted packets. */
   STAT_COUNTER recv;             /* Received packets. */
@@ -92,6 +94,7 @@ struct stats_igmp {
   STAT_COUNTER tx_report;        /* Sent reports. */
 };
 
+/** Memory stats */
 struct stats_mem {
 #if defined(LWIP_DEBUG) || LWIP_STATS_DISPLAY
   const char *name;
@@ -103,18 +106,21 @@ struct stats_mem {
   STAT_COUNTER illegal;
 };
 
+/** System element stats */
 struct stats_syselem {
   STAT_COUNTER used;
   STAT_COUNTER max;
   STAT_COUNTER err;
 };
 
+/** System stats */
 struct stats_sys {
   struct stats_syselem sem;
   struct stats_syselem mutex;
   struct stats_syselem mbox;
 };
 
+/** SNMP MIB2 stats */
 struct stats_mib2 {
   /* IP */
   u32_t ipinhdrerrors;
@@ -173,6 +179,7 @@ struct stats_mib2 {
   u32_t icmpoutechoreps;
 };
 
+/** SNMP MIB2 interface stats */
 struct stats_mib2_netif_ctrs {
   /* The total number of octets received on the interface, including framing characters */
   u32_t ifinoctets;
@@ -218,62 +225,81 @@ struct stats_mib2_netif_ctrs {
   u32_t ifouterrors;
 };
 
+/** lwIP stats container */
 struct stats_ {
 #if LINK_STATS
+  /** Link level */
   struct stats_proto link;
 #endif
 #if ETHARP_STATS
+  /** ARP */
   struct stats_proto etharp;
 #endif
 #if IPFRAG_STATS
+  /** Fragmentation */
   struct stats_proto ip_frag;
 #endif
 #if IP_STATS
+  /** IP */
   struct stats_proto ip;
 #endif
 #if ICMP_STATS
+  /** ICMP */
   struct stats_proto icmp;
 #endif
 #if IGMP_STATS
+  /** IGMP */
   struct stats_igmp igmp;
 #endif
 #if UDP_STATS
+  /** UDP */
   struct stats_proto udp;
 #endif
 #if TCP_STATS
+  /** TCP */
   struct stats_proto tcp;
 #endif
 #if MEM_STATS
+  /** Heap */
   struct stats_mem mem;
 #endif
 #if MEMP_STATS
+  /** Internal memory pools */
   struct stats_mem *memp[MEMP_MAX];
 #endif
 #if SYS_STATS
+  /** System */
   struct stats_sys sys;
 #endif
 #if IP6_STATS
+  /** IPv6 */
   struct stats_proto ip6;
 #endif
 #if ICMP6_STATS
+  /** ICMP6 */
   struct stats_proto icmp6;
 #endif
 #if IP6_FRAG_STATS
+  /** IPv6 fragmentation */
   struct stats_proto ip6_frag;
 #endif
 #if MLD6_STATS
+  /** Multicast listener discovery */
   struct stats_igmp mld6;
 #endif
 #if ND6_STATS
+  /** Neighbor discovery */
   struct stats_proto nd6;
 #endif
 #if MIB2_STATS
+  /** SNMP MIB2 */
   struct stats_mib2 mib2;
 #endif
 };
 
 extern struct stats_ lwip_stats;
 
+/** Init statistics */
 void stats_init(void);
 
 #define STATS_INC(x) ++lwip_stats.x