Added documentation

src/api/api_msg.c

@@ -377,6 +377,8 @@ pcb_new(struct api_msg_msg *msg)
 {
    msg->conn->err = ERR_OK;
 
+   LWIP_ASSERT("pcb_new: pcb already allocated", msg->conn->pcb.tcp == NULL);
+
    /* Allocate a PCB for this connection */
    switch(NETCONNTYPE_GROUP(msg->conn->type)) {
 #if LWIP_RAW
@@ -775,7 +777,7 @@ do_recv(struct api_msg_msg *msg)
  * @return ERR_OK
  *         ERR_MEM if LWIP_TCPIP_CORE_LOCKING=1 and sending hasn't yet finished
  */
-err_t
+static err_t
 do_writemore(struct netconn *conn)
 {
   err_t err;
@@ -996,7 +998,8 @@ do_join_leave_group(struct api_msg_msg *msg)
 #if LWIP_DNS
 /**
  * Callback function that is called when DNS name is resolved
- * (or on timeout).
+ * (or on timeout). A waiting application thread is waked up by
+ * signaling the semaphore.
  */
 static void
 do_dns_found(const char *name, struct ip_addr *ipaddr, void *arg)

src/include/lwip/api.h

@@ -93,29 +93,45 @@ enum netconn_igmp {
 };
 #endif /* LWIP_IGMP */
 
+/* forward-declare some structs to avoid to include their headers */
 struct ip_pcb;
 struct tcp_pcb;
 struct udp_pcb;
 struct raw_pcb;
 
+/** A netconn descriptor */
 struct netconn {
+  /** type of the netconn (TCP, UDP or RAW) */
   enum netconn_type type;
+  /** current state of the netconn */
   enum netconn_state state;
+  /** the lwIP internal protocol control block */
   union {
     struct ip_pcb  *ip;
     struct tcp_pcb *tcp;
     struct udp_pcb *udp;
     struct raw_pcb *raw;
   } pcb;
+  /** the last error this netconn had */
   err_t err;
+  /** mbox that is used mutex-like to synchroneously execute functions
+      in the core context */
   sys_mbox_t mbox;
+  /** mbox where received packets are stored until they are fetched
+      by the netconn application thread (can grow quite big) */
   sys_mbox_t recvmbox;
+  /** mbox where new connections are stored until processed
+      by the application thread */
   sys_mbox_t acceptmbox;
+  /** only used for socket layer */
   int socket;
 #if LWIP_SO_RCVTIMEO
+  /** timeout to wait for new data to be received
+      (or connections to arrive for listening netconns) */
   int recv_timeout;
 #endif /* LWIP_SO_RCVTIMEO */
 #if LWIP_SO_RCVBUF
+  /** maximum amount of bytes queued in recvmbox */
   int recv_bufsize;
 #endif /* LWIP_SO_RCVBUF */
   u16_t recv_avail;
@@ -131,7 +147,7 @@ struct netconn {
       if data couldn't be sent in the first try. */
   u8_t write_delayed;
 #endif /* LWIP_TCPIP_CORE_LOCKING */
-
+  /** A callback function that is informed about events for this netconn */
   void (* callback)(struct netconn *, enum netconn_evt, u16_t len);
 };
 

src/include/lwip/api_msg.h

@@ -49,50 +49,77 @@ enum netconn_igmp;
 /* IP addresses and port numbers are expected to be in
  * the same byte order as in the corresponding pcb.
  */
+/** This struct includes everything that is necessary to execute a function
+    for a netconn in another thread context (mainly used to process netconns
+    in the tcpip_thread context to be thread safe). */
 struct api_msg_msg {
+  /** The netconn which to process - always needed: it includes the semaphore
+      which is used to block the application thread until the function finished. */
   struct netconn *conn;
+  /** Depending on the executed function, one of these union members is used */
   union {
-    struct netbuf *b; /* do_send */
+    /** used for do_send */
+    struct netbuf *b;
+    /** used for do_newconn */
     struct {
       u8_t proto;
-    } n; /* do_newconn */
+    } n;
+    /** used for do_bind and do_connect */
     struct {
       struct ip_addr *ipaddr;
       u16_t port;
-    } bc; /* do_bind, do_connect */
+    } bc;
+    /** used for do_getaddr */
     struct {
       struct ip_addr *ipaddr;
       u16_t *port;
       u8_t local;
-    } ad; /* do_getaddr */
+    } ad;
+    /** used for do_write */
     struct {
       const void *dataptr;
       int len;
       u8_t apiflags;
-    } w; /* do_write */
+    } w;
+    /** used ofr do_recv */
     struct {
       u16_t len;
-    } r; /* do_recv */
+    } r;
 #if LWIP_IGMP
+    /** used for do_join_leave_group */
     struct {
       struct ip_addr *multiaddr;
       struct ip_addr *interface;
       enum netconn_igmp join_or_leave;
-    } jl; /* do_join_leave_group */
+    } jl;
 #endif /* LWIP_IGMP */
   } msg;
 };
 
+/** This struct contains a function to execute in another thread context and
+    a struct api_msg_msg that serves as an argument for this function.
+    This is passed to tcpip_apimsg to execute functions in tcpip_thread context. */
 struct api_msg {
+  /** function to execute in tcpip_thread context */
   void (* function)(struct api_msg_msg *msg);
+  /** arguments for this function */
   struct api_msg_msg msg;
 };
 
 #if LWIP_DNS
+/** As do_gethostbyname requires more arguments but doesn't require a netconn,
+    it has its own struct (to avoid struct api_msg getting bigger than necessary).
+    do_gethostbyname must be called using tcpip_callback instead of tcpip_apimsg
+    (see netconn_gethostbyname). */
 struct dns_api_msg {
+  /** Hostname to query or dotted IP address string */
   const char *name;
+  /** Rhe resolved address is stored here */
   struct ip_addr *addr;
+  /** This semaphore is posted when the name is resolved, the application thread
+      should wait on it. */
   sys_sem_t sem;
+  /** Errors are given back here */
   err_t *err;
 };
 #endif /* LWIP_DNS */