Improve lwIP doxygen documentation by copying several passages from rawapi.txt to the corresponding doxygen places

doc/doxygen/main_page.h

@@ -1,20 +1,32 @@
 /**
- * @defgroup lwip lwIP
- *
- * @defgroup infrastructure Infrastructure
- *
- * @defgroup callbackstyle_api Callback-style APIs
- * Non thread-safe APIs, callback style for maximum performance and minimum
- * memory footprint.
- * 
- * @defgroup sequential_api Sequential-style APIs
- * Sequential-style APIs, blocking functions. More overhead, but can be called
- * from any thread except TCPIP thread.
- * 
- * @defgroup netifs NETIFs
- * 
- * @defgroup apps Applications
- */
+  * @defgroup lwip lwIP
+  *
+  * @defgroup infrastructure Infrastructure
+  *
+  * @defgroup callbackstyle_api Callback-style APIs
+  * Non thread-safe APIs, callback style for maximum performance and minimum
+  * memory footprint.
+  * Program execution is driven by callbacks functions, which are then
+  * invoked by the lwIP core when activity related to that application
+  * occurs. A particular application may register to be notified via a
+  * callback function for events such as incoming data available, outgoing
+  * data sent, error notifications, poll timer expiration, connection
+  * closed, etc. An application can provide a callback function to perform
+  * processing for any or all of these events. Each callback is an ordinary
+  * C function that is called from within the TCP/IP code. Every callback
+  * function is passed the current TCP or UDP connection state as an
+  * argument. Also, in order to be able to keep program specific state,
+  * the callback functions are called with a program specified argument
+  * that is independent of the TCP/IP state.
+  * 
+  * @defgroup sequential_api Sequential-style APIs
+  * Sequential-style APIs, blocking functions. More overhead, but can be called
+  * from any thread except TCPIP thread.
+  * 
+  * @defgroup netifs NETIFs
+  * 
+  * @defgroup apps Applications
+  */
 
 /**
  * @mainpage Overview

src/core/tcp.c

@@ -11,6 +11,59 @@
  * Common functions for the TCP implementation, such as functinos
  * for manipulating the data structures and the TCP timer functions. TCP functions
  * related to input and output is found in tcp_in.c and tcp_out.c respectively.\n
+ * 
+ * TCP connection setup
+ * --------------------
+ * 
+ * The functions used for setting up connections is similar to that of
+ * the sequential API and of the BSD socket API. A new TCP connection
+ * identifier (i.e., a protocol control block - PCB) is created with the
+ * tcp_new() function. This PCB can then be either set to listen for new
+ * incoming connections or be explicitly connected to another host.
+ * - tcp_new()
+ * - tcp_bind()
+ * - tcp_listen() and tcp_listen_with_backlog()
+ * - tcp_accept()
+ * - tcp_connect()
+ * 
+ * Sending TCP data
+ * ----------------
+ * TCP data is sent by enqueueing the data with a call to
+ * tcp_write(). When the data is successfully transmitted to the remote
+ * host, the application will be notified with a call to a specified
+ * callback function.
+ * - tcp_write()
+ * - tcp_sent()
+ * 
+ * Receiving TCP data
+ * ------------------
+ * 
+ * TCP data reception is callback based - an application specified
+ * callback function is called when new data arrives. When the
+ * application has taken the data, it has to call the tcp_recved()
+ * function to indicate that TCP can advertise increase the receive
+ * window.
+ * - tcp_recv()
+ * - tcp_recved()
+ * 
+ * Application polling
+ * -------------------
+ * When a connection is idle (i.e., no data is either transmitted or
+ * received), lwIP will repeatedly poll the application by calling a
+ * specified callback function. This can be used either as a watchdog
+ * timer for killing connections that have stayed idle for too long, or
+ * as a method of waiting for memory to become available. For instance,
+ * if a call to tcp_write() has failed because memory wasn't available,
+ * the application may use the polling functionality to call tcp_write()
+ * again when the connection has been idle for a while.
+ * - tcp_poll()
+ *
+ * Closing and aborting connections
+ * --------------------------------
+ * - tcp_close()
+ * - tcp_abort()
+ * - tcp_err()
+ * 
  */
 
 /*