Lots of documentation updates

doc/doxygen/lwip.Doxyfile

@@ -842,7 +842,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../../src/include/netif/ppp/polarssl
+EXCLUDE                = ../../src/include/netif/ppp/polarssl \
+                         ../../src/include/lwip/priv
 
 # 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
@@ -2094,6 +2095,14 @@ PREDEFINED             = NO_SYS=0 \
                          LWIP_DNS=1 \
                          LWIP_SOCKETS=1 \
                          LWIP_NETCONN=1 \
+                         IP_SOF_BROADCAST=1 \
+                         IP_SOF_BROADCAST_RECV=1 \
+                         LWIP_NETIF_API=1 \
+                         LWIP_SO_SNDTIMEO=1 \
+                         LWIP_SO_RCVBUF=1 \
+                         LWIP_SO_LINGER=1 \
+                         SO_REUSE=1 \
+                         SO_REUSE_RXTOALL=1 \
                          "LWIP_DNS && LWIP_SOCKET   " \
                          "(LWIP_DNS && LWIP_SOCKET)=1   "
 

src/include/lwip/apps/netbiosns.h

@@ -34,11 +34,13 @@
 
 #include "lwip/apps/netbiosns_opts.h"
 
+/** Init netbios responder */
 void netbiosns_init(void);
 #ifndef NETBIOS_LWIP_NAME
-/* ATTENTION: the hostname must be <= 15 characters! */
+/** Set netbios name. ATTENTION: the hostname must be <= 15 characters! */
 void netbiosns_set_name(const char* hostname);
 #endif
+/** Stop netbios responder */
 void netbiosns_stop(void);
 
 #endif /* LWIP_HDR_APPS_NETBIOS_H */

src/include/lwip/err.h

@@ -53,25 +53,42 @@ typedef s8_t err_t;
 
 /* Definitions for error constants. */
 
-#define ERR_OK          0    /* No error, everything OK. */
+/** No error, everything OK. */
-#define ERR_MEM        -1    /* Out of memory error.     */
+#define ERR_OK          0 
-#define ERR_BUF        -2    /* Buffer error.            */
+/** Out of memory error.     */
-#define ERR_TIMEOUT    -3    /* Timeout.                 */
+#define ERR_MEM        -1
-#define ERR_RTE        -4    /* Routing problem.         */
+/** Buffer error.            */
-#define ERR_INPROGRESS -5    /* Operation in progress    */
+#define ERR_BUF        -2
-#define ERR_VAL        -6    /* Illegal value.           */
+/** Timeout.                 */
-#define ERR_WOULDBLOCK -7    /* Operation would block.   */
+#define ERR_TIMEOUT    -3
-#define ERR_USE        -8    /* Address in use.          */
+/** Routing problem.         */
-#define ERR_ALREADY    -9    /* Already connecting.      */
+#define ERR_RTE        -4
-#define ERR_ISCONN     -10   /* Conn already established.*/
+/** Operation in progress    */
-#define ERR_CONN       -11   /* Not connected.           */
+#define ERR_INPROGRESS -5
-#define ERR_IF         -12   /* Low-level netif error    */
+/** Illegal value.           */
+#define ERR_VAL        -6
+/** Operation would block.   */
+#define ERR_WOULDBLOCK -7
+/** Address in use.          */
+#define ERR_USE        -8
+/** Already connecting.      */
+#define ERR_ALREADY    -9
+/** Conn already established.*/
+#define ERR_ISCONN     -10
+/** Not connected.           */
+#define ERR_CONN       -11
+/** Low-level netif error    */
+#define ERR_IF         -12
 
 #define ERR_IS_FATAL(e) ((e) <= ERR_ABRT)
-#define ERR_ABRT       -13   /* Connection aborted.      */
+/** Connection aborted.      */
-#define ERR_RST        -14   /* Connection reset.        */
+#define ERR_ABRT       -13
-#define ERR_CLSD       -15   /* Connection closed.       */
+/** Connection reset.        */
-#define ERR_ARG        -16   /* Illegal argument.        */
+#define ERR_RST        -14
+/** Connection closed.       */
+#define ERR_CLSD       -15
+/** Illegal argument.        */
+#define ERR_ARG        -16
 
 #ifdef LWIP_DEBUG
 extern const char *lwip_strerr(err_t err);

src/include/lwip/icmp.h

@@ -64,18 +64,28 @@ extern "C" {
 #define ICMP_AM  17    /* address mask request */
 #define ICMP_AMR 18    /* address mask reply */
 
+/** ICMP destination unreachable codes */
 enum icmp_dur_type {
-  ICMP_DUR_NET   = 0,  /* net unreachable */
+  /** net unreachable */
-  ICMP_DUR_HOST  = 1,  /* host unreachable */
+  ICMP_DUR_NET   = 0,
-  ICMP_DUR_PROTO = 2,  /* protocol unreachable */
+  /** host unreachable */
-  ICMP_DUR_PORT  = 3,  /* port unreachable */
+  ICMP_DUR_HOST  = 1,
-  ICMP_DUR_FRAG  = 4,  /* fragmentation needed and DF set */
+  /** protocol unreachable */
-  ICMP_DUR_SR    = 5   /* source route failed */
+  ICMP_DUR_PROTO = 2,
+  /** port unreachable */
+  ICMP_DUR_PORT  = 3,
+  /** fragmentation needed and DF set */
+  ICMP_DUR_FRAG  = 4,
+  /** source route failed */
+  ICMP_DUR_SR    = 5
 };
 
+/** ICMP time exceeded codes */
 enum icmp_te_type {
-  ICMP_TE_TTL  = 0,    /* time to live exceeded in transit */
+  /* time to live exceeded in transit */
-  ICMP_TE_FRAG = 1     /* fragment reassembly time exceeded */
+  ICMP_TE_TTL  = 0,
+  /** fragment reassembly time exceeded */
+  ICMP_TE_FRAG = 1
 };
 
 #ifdef PACK_STRUCT_USE_INCLUDES

src/include/lwip/icmp6.h

@@ -51,52 +51,91 @@
 extern "C" {
 #endif
 
+/** ICMP type */
 enum icmp6_type {
-  ICMP6_TYPE_DUR = 1,  /* Destination unreachable */
+  /** Destination unreachable */
-  ICMP6_TYPE_PTB = 2,  /* Packet too big */
+  ICMP6_TYPE_DUR = 1,
-  ICMP6_TYPE_TE = 3,   /* Time exceeded */
+  /** Packet too big */
-  ICMP6_TYPE_PP = 4,   /* Parameter problem */
+  ICMP6_TYPE_PTB = 2,
-  ICMP6_TYPE_PE1 = 100,  /* Private experimentation */
+  /** Time exceeded */
-  ICMP6_TYPE_PE2 = 101,  /* Private experimentation */
+  ICMP6_TYPE_TE = 3,
-  ICMP6_TYPE_RSV_ERR = 127,  /* Reserved for expansion of error messages */
+  /** Parameter problem */
+  ICMP6_TYPE_PP = 4,
+  /** Private experimentation */
+  ICMP6_TYPE_PE1 = 100,  
+  /** Private experimentation */
+  ICMP6_TYPE_PE2 = 101,
+  /** Reserved for expansion of error messages */
+  ICMP6_TYPE_RSV_ERR = 127,
 
-  ICMP6_TYPE_EREQ = 128,  /* Echo request */
+  /** Echo request */
-  ICMP6_TYPE_EREP = 129,  /* Echo reply */
+  ICMP6_TYPE_EREQ = 128,
-  ICMP6_TYPE_MLQ = 130,  /* Multicast listener query */
+  /** Echo reply */
-  ICMP6_TYPE_MLR = 131,  /* Multicast listener report */
+  ICMP6_TYPE_EREP = 129,
-  ICMP6_TYPE_MLD = 132,  /* Multicast listener done */
+  /** Multicast listener query */
-  ICMP6_TYPE_RS = 133,  /* Router solicitation */
+  ICMP6_TYPE_MLQ = 130,  
-  ICMP6_TYPE_RA = 134,  /* Router advertisement */
+  /** Multicast listener report */
-  ICMP6_TYPE_NS = 135,  /* Neighbor solicitation */
+  ICMP6_TYPE_MLR = 131,
-  ICMP6_TYPE_NA = 136,  /* Neighbor advertisement */
+  /** Multicast listener done */
-  ICMP6_TYPE_RD = 137,  /* Redirect */
+  ICMP6_TYPE_MLD = 132,
-  ICMP6_TYPE_MRA = 151,  /* Multicast router advertisement */
+  /** Router solicitation */
-  ICMP6_TYPE_MRS = 152,  /* Multicast router solicitation */
+  ICMP6_TYPE_RS = 133,
-  ICMP6_TYPE_MRT = 153,  /* Multicast router termination */
+  /** Router advertisement */
-  ICMP6_TYPE_PE3 = 200,  /* Private experimentation */
+  ICMP6_TYPE_RA = 134,
-  ICMP6_TYPE_PE4 = 201,  /* Private experimentation */
+  /** Neighbor solicitation */
-  ICMP6_TYPE_RSV_INF = 255  /* Reserved for expansion of informational messages */
+  ICMP6_TYPE_NS = 135,
+  /** Neighbor advertisement */
+  ICMP6_TYPE_NA = 136,
+  /** Redirect */
+  ICMP6_TYPE_RD = 137,
+  /** Multicast router advertisement */
+  ICMP6_TYPE_MRA = 151,
+  /** Multicast router solicitation */
+  ICMP6_TYPE_MRS = 152,
+  /** Multicast router termination */
+  ICMP6_TYPE_MRT = 153,
+  /** Private experimentation */
+  ICMP6_TYPE_PE3 = 200,
+  /** Private experimentation */
+  ICMP6_TYPE_PE4 = 201,
+  /** Reserved for expansion of informational messages */
+  ICMP6_TYPE_RSV_INF = 255
 };
 
+/** ICMP destination unreachable codes */
 enum icmp6_dur_code {
-  ICMP6_DUR_NO_ROUTE = 0,     /* No route to destination */
+  /** No route to destination */
-  ICMP6_DUR_PROHIBITED = 1,   /* Communication with destination administratively prohibited */
+  ICMP6_DUR_NO_ROUTE = 0,
-  ICMP6_DUR_SCOPE = 2,        /* Beyond scope of source address */
+  /** Communication with destination administratively prohibited */
-  ICMP6_DUR_ADDRESS = 3,      /* Address unreachable */
+  ICMP6_DUR_PROHIBITED = 1,
-  ICMP6_DUR_PORT = 4,         /* Port unreachable */
+  /** Beyond scope of source address */
-  ICMP6_DUR_POLICY = 5,       /* Source address failed ingress/egress policy */
+  ICMP6_DUR_SCOPE = 2,
-  ICMP6_DUR_REJECT_ROUTE = 6  /* Reject route to destination */
+  /** Address unreachable */
+  ICMP6_DUR_ADDRESS = 3,
+  /** Port unreachable */
+  ICMP6_DUR_PORT = 4,
+  /** Source address failed ingress/egress policy */
+  ICMP6_DUR_POLICY = 5,
+  /** Reject route to destination */
+  ICMP6_DUR_REJECT_ROUTE = 6
 };
 
+/** ICMP time exceeded codes */
 enum icmp6_te_code {
-  ICMP6_TE_HL = 0,   /* Hop limit exceeded in transit */
+  /** Hop limit exceeded in transit */
-  ICMP6_TE_FRAG = 1  /* Fragment reassembly time exceeded */
+  ICMP6_TE_HL = 0,
+  /** Fragment reassembly time exceeded */
+  ICMP6_TE_FRAG = 1
 };
 
+/** ICMP parameter code */
 enum icmp6_pp_code {
-  ICMP6_PP_FIELD = 0,   /* Erroneous header field encountered */
+  /** Erroneous header field encountered */
-  ICMP6_PP_HEADER = 1,  /* Unrecognized next header type encountered */
+  ICMP6_PP_FIELD = 0,
-  ICMP6_PP_OPTION = 2   /* Unrecognized IPv6 option encountered */
+  /** Unrecognized next header type encountered */
+  ICMP6_PP_HEADER = 1,
+  /** Unrecognized IPv6 option encountered */
+  ICMP6_PP_OPTION = 2
 };
 
 /** This is the standard ICMP6 header. */

src/include/lwip/netbuf.h

@@ -56,6 +56,7 @@ extern "C" {
 /** This netbuf includes a checksum */
 #define NETBUF_FLAG_CHKSUM      0x02
 
+/** "Network buffer" - contains data and addressing info */
 struct netbuf {
   struct pbuf *p, *ptr;
   ip_addr_t addr;

src/include/lwip/raw.h

@@ -66,6 +66,7 @@ struct raw_pcb;
 typedef u8_t (*raw_recv_fn)(void *arg, struct raw_pcb *pcb, struct pbuf *p,
     const ip_addr_t *addr);
 
+/** the RAW protocol control block */
 struct raw_pcb {
   /* Common members of all PCB types */
   IP_PCB;

src/include/lwip/udp.h

@@ -93,8 +93,9 @@ struct udp_pcb;
 typedef void (*udp_recv_fn)(void *arg, struct udp_pcb *pcb, struct pbuf *p,
     const ip_addr_t *addr, u16_t port);
 
+/** the UDP protocol control block */
 struct udp_pcb {
-/* Common members of all PCB types */
+/** Common members of all PCB types */
   IP_PCB;
 
 /* Protocol specific PCB members */