Update docs

docs/api-reference/apps/netconn.rst

@@ -3,4 +3,107 @@
 Netconn API
 ===========
 
+*Netconn API* is addon on top of existing connection module and allows sending and receiving data with sequential API calls, similar to *POSIX socket* API.
+
+It can operate in client or server mode and uses operating system features, such as message queues and semaphore to link non-blocking callback API for connections with sequential API for application thread.
+
+.. note::
+    Connection API does not directly allow receiving data with sequential and linear code execution.
+    All is based on connection event system. 
+    Netconn adds this functionality as it is implemented on top of regular connection API.
+
+.. warning::
+    Netconn API are designed to be called from application threads ONLY. 
+    It is not allowed to call any of *netconn API* functions from within interrupt or callback event functions.
+
+Netconn client
+^^^^^^^^^^^^^^
+
+.. figure:: ../../static/images/netconn_client.svg
+	:align: center
+	:alt: Netconn API client block diagram
+
+	Netconn API client block diagram
+
+Above block diagram shows basic architecture of netconn client application. 
+There is always one application thread (in green) which calls *netconn API* functions to interact with connection API in synchronous mode.
+
+Every netconn connection uses dedicated structure to handle message queue for data received packet buffers.
+Each time new packet is received (red block, *data received event*), reference to it is written to message queue of netconn structure, while application thread reads new entries from the same queue to get packets.
+
+.. literalinclude:: ../../../snippets/netconn_client.c
+	:language: c
+
+Netconn server
+^^^^^^^^^^^^^^
+
+.. figure:: ../../static/images/netconn_server_1thread.svg
+	:align: center
+	:alt: Netconn API server block diagram
+
+	Netconn API server block diagram
+
+When netconn is configured in server mode, it is possible to accept new clients from remote side.
+Application creates *netconn server connection*, which can only accept *clients* and cannot send/receive any data.
+It configures server on dedicated port (selected by application) and listens on it.
+
+When new client connects, *server callback function* is called with *new active connection event*. 
+Newly accepted connection is then written to server structure netconn which is later read by application thread.
+At the same time, *netconn connection* structure (blue) is created to allow standard send/receive operation on active connection.
+
+.. note::
+    Each connected client has its own *netconn connection* structure. 
+    When multiple clients connect to server at the same time, multiple entries are written to *connection accept* message queue and are ready to be processed by application thread.
+
+From this point, program flow is the same as in case of *netconn client*.
+
+This is basic example for netconn thread.
+It waits for client and processes it in blocking mode.
+
+.. warning::
+    When multiple clients connect at the same time to netconn server,
+    they are processed one-by-one, sequentially. This may introduce delay in response for other clients.
+    Check netconn concurrency option to process multiple clients at the same time
+
+.. literalinclude:: ../../../snippets/netconn_server_1thread.c
+	:language: c
+
+Netconn server concurrency
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../static/images/netconn_server_concurrency.svg
+	:align: center
+	:alt: Netconn API server concurrency block diagram
+
+	Netconn API server concurrency block diagram
+
+When compared to classic netconn server, concurrent netconn server mode allows multiple clients to be processed at the same time.
+This can drastically improve performance and response time on clients side, especially when many clients are connected to server at the same time.
+
+Every time *server application thread* (green block) gets new client to process, it starts a new *processing* thread instead of doing it in accept thread. 
+
+* Server thread is only dedicated to accept clients and start threads
+* Multiple processing thread can run in parallel to send/receive data from multiple clients
+* No delay when multi clients are active at the same time
+* Higher memory footprint is necessary as there are multiple threads active
+
+.. literalinclude:: ../../../snippets/netconn_server.c
+	:language: c
+
+Non-blocking receive
+^^^^^^^^^^^^^^^^^^^^
+
+By default, netconn API is written to only work in separate application thread,
+dedicated for network connection processing. Because of that, by default every function is fully blocking.
+It will wait until result is ready to be used by application.
+
+It is, however, possible to enable timeout feature for receiving data only.
+When this feature is enabled, :cpp:func:`esp_netconn_receive` will block for maximal timeout set with
+:cpp:func:`esp_netconn_set_receive_timeout` function.
+
+When enabled, if there is no received data for timeout amount of time, function will return with timeout status and application needs to process it accordingly.
+
+.. tip::
+    :c:macro:`ESP_CFG_NETCONN_RECEIVE_TIMEOUT` must be set to ``1`` to use this feature.
+
 .. doxygengroup:: ESP_NETCONN

docs/api-reference/esp/debug.rst

@@ -3,4 +3,33 @@
 Debug support
 =============
 
+Middleware has extended debugging capabilities. 
+These consist of different debugging levels and types of debug messages,
+allowing to track and catch different types of warnings, severe problems or simply output messages
+program flow messages (trace messages).
+
+Module is highly configurable using library configuration methods.
+Application must enable some options to decide what type of messages and for which modules it would like to output messages.
+
+With default configuration, ``printf`` is used as output function.
+This behavior can be changed with :c:macro:`ESP_CF_DBG_OUT` configuration.
+
+For successful debugging, application must:
+
+* Enable global debugging by setting :c:macro:`ESP_CFG_DBG` to :c:macro:`ESP_DBG_ON`
+* Configure which types of messages to output
+* Configure debugging level, from all messages to severe only
+* Enable specific modules to debug, by setting its configuration value to :c:macro:`ESP_DBG_ON`
+
+.. tip::
+    Check :ref:`api_esp_config` for all modules with debug implementation.
+
+An example code with config and latter usage:
+
+.. literalinclude:: ../../examples_src/debug_config.h
+    :language: c
+
+.. literalinclude:: ../../examples_src/debug.c
+    :language: c
+
 .. doxygengroup:: ESP_DEBUG

docs/api-reference/esp/pbuf.rst

@@ -53,7 +53,7 @@ It is used to properly handle memory free operation, especially when *pbuf* is u
 .. note::
 	If there would be no reference counter information and application would free memory while another part of library still uses its reference, application would invoke *undefined behavior* and system could crash instantly.
 
-When application tries to free pbuf chain as on first image, it would normally call ``esp_pbuf_free`` function. That would:
+When application tries to free pbuf chain as on first image, it would normally call :cpp:func:`esp_pbuf_free` function. That would:
 
 * Decrease reference counter by ``1``
 * If reference counter ``== 0``, free packet buffer
@@ -79,7 +79,7 @@ As per first example, result of freeing would look similar to image and table be
 
 .. note::
 	*Block 1* has been successfully freed, but since *block 2* had reference counter set to ``2`` before, it was only decreased by ``1`` to a new value ``1`` and free operation stopped instead.
-	*User variable 2* is still using *pbuf* starting at *block 2* and must manually call ``esp_pbuf_free`` to free it.
+	*User variable 2* is still using *pbuf* starting at *block 2* and must manually call :cpp:func:`esp_pbuf_free` to free it.
 
 Concatenating vs chaining
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -106,7 +106,7 @@ Concat operation shall be used when ``2`` pbufs are linked together and referenc
 After concating *2 pbufs* together, reference counter of second is still set to ``1``, however we can see that ``2`` pointers point to *second pbuf*.
 
 .. note::
-	After application calls ``esp_pbuf_cat``, it must not use pointer which points to *second pbuf*.
+	After application calls :cpp:func:`esp_pbuf_cat`, it must not use pointer which points to *second pbuf*.
 	This would invoke *undefined behavior* if one pointer tries to free memory while second still points to it.
 
 An example code showing proper usage of concat operation:
@@ -128,7 +128,8 @@ Chain operation shall be used when ``2`` pbufs are linked together and reference
 After chainin *2 pbufs* together, reference counter of second is increased by ``1``, which allows application to reference second *pbuf* separatelly.
 
 .. note::
-	After application calls ``esp_pbuf_chain``, it also has to manually free its reference using ``esp_pbuf_free`` function.
+	After application calls :cpp:func:`esp_pbuf_chain`,
+	it also has to manually free its reference using :cpp:func:`esp_pbuf_free` function.
 	Forgetting to free pbuf invokes memory leak
 
 An example code showing proper usage of chain operation:

docs/examples_src/debug_config.h

@@ -1,13 +1,14 @@
 /* Modifications of esp_config.h file for configuration */
 
 /* Enable global debug */
-#define ESP_CFG_DBG                             ESP_DBG_ON
+#define ESP_CFG_DBG                 ESP_DBG_ON
 
 /*
  * Enable debug types. 
- * You may use OR | to use multiple types: ESP_DBG_TYPE_TRACE | ESP_DBG_TYPE_STATE
+ * Application may use bitwise OR | to use multiple types:
+ *    ESP_DBG_TYPE_TRACE | ESP_DBG_TYPE_STATE
  */
-#define ESP_CFG_DBG_TYPES_ON                    ESP_DBG_TYPE_TRACE
+#define ESP_CFG_DBG_TYPES_ON        ESP_DBG_TYPE_TRACE
 
 /* Enable debug on custom module */
-#define MY_DBG_MODULE                           ESP_DBG_ON
+#define MY_DBG_MODULE               ESP_DBG_ON