Added inline source documentation.

src/core/pbuf.c

@@ -183,7 +183,7 @@ pbuf_pool_alloc(void)
 
 
 /**
- * Allocates a 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
  * layer at which the pbuf is allocated and the requested size
@@ -319,7 +319,7 @@ pbuf_alloc(pbuf_layer l, u16_t length, pbuf_flag flag)
     LWIP_ASSERT("pbuf_alloc: pbuf->payload properly aligned",
            ((mem_ptr_t)p->payload % MEM_ALIGNMENT) == 0);
     break;
-  /* pbuf references existing (static constant) ROM payload? */
+  /* pbuf references existing (non-volatile static constant) ROM payload? */
   case PBUF_ROM:
   /* pbuf references existing (externally allocated) RAM payload? */
   case PBUF_REF:
@@ -664,8 +664,8 @@ pbuf_cat(struct pbuf *h, struct pbuf *t)
 {
   struct pbuf *p;
 
-  LWIP_ASSERT("h != NULL", h != NULL);
+  LWIP_ASSERT("h != NULL (programmer violates API)", h != NULL);
-  LWIP_ASSERT("t != NULL", t != NULL);
+  LWIP_ASSERT("t != NULL (programmer violates API)", t != NULL);
   if ((h == NULL) || (t == NULL)) return;
 
   /* proceed to last pbuf of chain */
@@ -675,10 +675,14 @@ pbuf_cat(struct pbuf *h, struct pbuf *t)
   }
   /* { p is last pbuf of first h chain, p->next == NULL } */
   LWIP_ASSERT("p->tot_len == p->len (of last pbuf in chain)", p->tot_len == p->len);
+  LWIP_ASSERT("p->next == NULL", p->next == NULL);
   /* add total length of second chain to last pbuf total of first chain */
   p->tot_len += t->tot_len;
   /* chain last pbuf of head (p) with first of tail (t) */
   p->next = t;
+  /* p->next now references t, but the caller will drop its reference to t,
+   * so netto there is no change to the reference count of t.
+   */
 }
 
 /**
@@ -792,7 +796,7 @@ pbuf_dequeue(struct pbuf *p)
   /* { p->tot_len == p->len } => p is the last pbuf of the first packet */
   /* remember next packet on queue in q */
   q = p->next;
-  /* dequeue p from queue */
+  /* dequeue packet p from queue */
   p->next = NULL;
   /* any next packet on queue? */
   if (q != NULL) {

src/core/tcp_out.c

@@ -62,16 +62,21 @@ static void tcp_output_segment(struct tcp_seg *seg, struct tcp_pcb *pcb);
 err_t
 tcp_send_ctrl(struct tcp_pcb *pcb, u8_t flags)
 {
+  /* no data, no length, flags, copy=1, no optdata, no optdatalen */
   return tcp_enqueue(pcb, NULL, 0, flags, 1, NULL, 0);
-
 }
 
-/*
+/**
- * NB. tcp_write() enqueues data for sending, but does not send it
+ * Write data for sending (but does not send it immediately).
- * straight away.  It waits in the expectation of more data being sent
+ *
- * soon (as it can send them more efficiently by combining them
+ * It waits in the expectation of more data being sent soon (as
- * together).  To prompt the system to send data now, call
+ * it can send them more efficiently by combining them together).
- * tcp_output() after calling tcp_write().
+ * To prompt the system to send data now, call tcp_output() after
+ * calling tcp_write().
+ * 
+ * @arg pcb Protocol control block of the TCP connection to enqueue data for. 
+ * 
+ * @see tcp_write()
  */
 
 err_t
@@ -95,12 +100,16 @@ tcp_write(struct tcp_pcb *pcb, const void *arg, u16_t len, u8_t copy)
 }
 
 /**
- * Enqueue data for tranmission
+ * Enqueue either data or TCP options (but not both) for tranmission
+ * 
+ * 
  * 
  * @arg pcb Protocol control block for the TCP connection to enqueue data for.
  * @arg arg Pointer to the data to be enqueued for sending.
  * @arg len Data length in bytes
  * @arg flags
+ * @arg copy 1 if data must be copied, 0 if data is non-volatile and can be
+ * referenced.
  * @arg optdata
  * @arg optlen
  */
@@ -118,6 +127,10 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
 
   LWIP_DEBUGF(TCP_OUTPUT_DEBUG, ("tcp_enqueue(pcb=%p, arg=%p, len=%u, flags=%x, copy=%u)\n",
     (void *)pcb, arg, len, (unsigned int)flags, (unsigned int)copy));
+  LWIP_ASSERT("tcp_enqueue: len == 0 || optlen == 0 (programmer violates API)",
+      len == 0 || optlen == 0);
+  LWIP_ASSERT("tcp_enqueue: arg == NULL || optdata == NULL (programmer violates API)",
+      arg == NULL || optdata == NULL);
   /* fail on too much data */
   if (len > pcb->snd_buf) {
     LWIP_DEBUGF(TCP_OUTPUT_DEBUG | 3, ("tcp_enqueue: too much data (len=%u > snd_buf=%u)\n", len, pcb->snd_buf));
@@ -132,18 +145,18 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
 
   LWIP_DEBUGF(TCP_QLEN_DEBUG, ("tcp_enqueue: queuelen: %u\n", (unsigned int)pcb->snd_queuelen));
 
-  /* Check if the queue length exceeds the configured maximum queue
+  /* If total number of pbufs on the unsent/unacked queues exceeds the
-   * length. If so, we return an error. */
+   * configured maximum, return an error */
   queuelen = pcb->snd_queuelen;
   if (queuelen >= TCP_SND_QUEUELEN) {
     LWIP_DEBUGF(TCP_OUTPUT_DEBUG | 3, ("tcp_enqueue: too long queue %u (max %u)\n", queuelen, TCP_SND_QUEUELEN));
     goto memerr;
   }
   if (queuelen != 0) {
-    LWIP_ASSERT("tcp_enqueue: queue length non-zero and at least one queue non-empty",
+    LWIP_ASSERT("tcp_enqueue: pbufs on queue => at least one queue non-empty",
       pcb->unacked != NULL || pcb->unsent != NULL);
   } else {
-    LWIP_ASSERT("tcp_enqueue: queue length zero and queues empty",
+    LWIP_ASSERT("tcp_enqueue: no pbufs on queue => both queues empty",
       pcb->unacked == NULL && pcb->unsent == NULL);
   }
 
@@ -168,17 +181,16 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
 
     /* first segment of to-be-queued data? */
     if (queue == NULL) {
-      useg = queue = seg;
+      queue = seg;
     }
     /* subsequent segments of to-be-queued data */
     else {
-      /* Attach the segment to the end of the queued segments. */
+      /* Attach the segment to the end of the queued segments */
       LWIP_ASSERT("useg != NULL", useg != NULL);
       useg->next = seg;
-      /* remember last segment of to-be-queued data for next iteration */
-      useg = seg;
     }
-    /* { useg == seg } */
+    /* remember last segment of to-be-queued data for next iteration */
+    useg = seg;
 
     /* If copy is set, memory should be allocated
      * and data copied into pbuf, otherwise data comes from
@@ -207,7 +219,6 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
     }
     /* do not copy data */
     else {
-
       /* First, allocate a pbuf for holding the data.
        * since the referenced data is available at least until it is sent out on the
        * link (as it has to be ACKed by the remote party) we can safely use PBUF_ROM
@@ -328,6 +339,7 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
   }
   pcb->snd_lbb += len;
   pcb->snd_buf -= len;
+  /* update number of segments on the queues */
   pcb->snd_queuelen = queuelen;
   LWIP_DEBUGF(TCP_QLEN_DEBUG, ("tcp_enqueue: %d (after enqueued)\n", pcb->snd_queuelen));
   if (pcb->snd_queuelen != 0) {

src/include/lwip/tcp.h

@@ -213,18 +213,13 @@ enum tcp_state {
   TIME_WAIT   = 10
 };
 
-
 /* the TCP protocol control block */
 struct tcp_pcb {
-/* Common members of all PCB types */
+/** common PCB members */
   IP_PCB;
-
+/** protocol specific PCB members */
-/* Protocol specific PCB members */
+  struct tcp_pcb *next; /* for the linked list */
-
+  enum tcp_state state; /* TCP state */
-  struct tcp_pcb *next;   /* for the linked list */
-
-  enum tcp_state state;   /* TCP state */
-
   u8_t prio;
   void *callback_arg;
 
@@ -240,7 +235,7 @@ struct tcp_pcb {
 #define TF_GOT_FIN   (u8_t)0x20U   /* Connection was closed by the remote end. */
 #define TF_NODELAY   (u8_t)0x40U   /* Disable Nagle algorithm */
 
-  /* receiver varables */
+  /* receiver variables */
   u32_t rcv_nxt;   /* next seqno expected */
   u16_t rcv_wnd;   /* receiver window */
   
@@ -253,10 +248,10 @@ struct tcp_pcb {
   
   u16_t mss;   /* maximum segment size */
   
-  /* RTT estimation variables. */
+  /* RTT (round trip time) estimation variables */
   u32_t rttest; /* RTT estimate in 500ms ticks */
   u32_t rtseq;  /* sequence number being timed */
-  s16_t sa, sv;
+  s16_t sa, sv; /* @todo document this */
 
   u16_t rto;    /* retransmission time-out */
   u8_t nrtx;    /* number of retransmissions */
@@ -392,7 +387,7 @@ err_t lwip_tcp_event(void *arg, struct tcp_pcb *pcb,
                         (errf)((arg),(err))
 #endif /* LWIP_EVENT_API */
 
-/* This structure is used to repressent TCP segments when queued. */
+/* This structure represents a TCP segment on the unsent and unacked queues */
 struct tcp_seg {
   struct tcp_seg *next;    /* used when putting segements on a queue */
   struct pbuf *p;          /* buffer containing data + TCP header */