Update docs with captions for code

docs/api-reference/apps/netconn.rst

@@ -32,16 +32,17 @@ Every netconn connection uses dedicated structure to handle message queue for da
 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
+    :language: c
+    :caption: Netconn client example
 
 Netconn server
 ^^^^^^^^^^^^^^
 
 .. figure:: ../../static/images/netconn_server_1thread.svg
-	:align: center
-	:alt: Netconn API server block diagram
+    :align: center
+    :alt: Netconn API server block diagram
 
-	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.
@@ -67,6 +68,7 @@ It waits for client and processes it in blocking mode.
 
 .. literalinclude:: ../../../snippets/netconn_server_1thread.c
 	:language: c
+    :caption: Netconn server with single processing thread
 
 Netconn server concurrency
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -89,6 +91,7 @@ Every time *server application thread* (green block) gets new client to process,
 
 .. literalinclude:: ../../../snippets/netconn_server.c
 	:language: c
+    :caption: Netconn server with multiple processing threads
 
 Non-blocking receive
 ^^^^^^^^^^^^^^^^^^^^

docs/api-reference/esp/conn.rst

@@ -3,4 +3,65 @@
 Connections
 ===========
 
+Connections are essential feature of WiFi device and middleware.
+It is developed with strong focus on its performance and since it may interact with huge amount of data,
+it tries to use zero-copy (when available) feature, to decrease processing time.
+
+*ESP AT Firmware* by default supports up to ``5`` connections being active at the same time and supports:
+
+* Up to ``5`` TCP connections active at the same time
+* Up to ``5`` UDP connections active at the same time
+* Up to ``1`` SSL connection active at a time
+
+.. note::
+    Client or server connections are available. 
+    Same API function call are used to send/receive data or close connection.
+
+Architecture of the connection API is using callback event functions.
+This allows maximal optimization in terms of responsiveness on different kind of events.
+
+Example below shows *bare minimum* implementation to:
+
+* Start a new connection to remote host
+* Send *HTTP GET* request to remote host
+* Process received data in event and print number of received bytes 
+
+.. literalinclude:: ../../../snippets/client.c
+	:language: c
+	:caption: Client connection minimum example
+
+Sending data
+^^^^^^^^^^^^
+
+Receiving data flow is always the same. Whenever new data packet arrives, corresponding event is called to notify application layer.
+When it comes to sending data, application may decide between ``2`` options (*this is valid only for non-UDP connections):
+
+* Write data to temporary transmit buffer
+* Execute *send command* for every API function call
+
+Temporary transmit buffer
+*************************
+
+By calling :cpp:func:`esp_conn_write` on active connection, temporary buffer is allocated and input data are copied to it.
+There is always up to ``1`` internal buffer active. When it is full (or if input data length is longer than maximal size),
+data are immediately send out and are not written to buffer.
+
+*ESP AT Firmware* allows (current revision) to transmit up to ``2048`` bytes at a time with single command.
+When trying to send more than this, application would need to issue multiple *send commands* on *AT commands level*.
+
+Write option is used mostly when application needs to write many different small chunks of data.
+Temporary buffer hence prevents many *send command* instructions as it is faster to send single command with big buffer,
+than many of them with smaller chunks of bytes.
+
+.. literalinclude:: ../../examples_src/conn_write.c
+	:language: c
+	:caption: Write data to connection output buffer
+
+Transmit packet manually
+************************
+
+In some cases it is not possible to use temporary buffers, 
+mostly because of memory constraints.
+Application can directly start *send data* instructions on *AT* level by using :cpp:func:`esp_conn_send` or :cpp:func:`esp_conn_sendto` functions.
+
 .. doxygengroup:: ESP_CONN

docs/api-reference/esp/debug.rst

@@ -28,8 +28,10 @@ An example code with config and latter usage:
 
 .. literalinclude:: ../../examples_src/debug_config.h
     :language: c
+    :caption: Debug configuration setup
 
 .. literalinclude:: ../../examples_src/debug.c
     :language: c
+    :caption: Debug usage within middleware
 
 .. doxygengroup:: ESP_DEBUG

docs/api-reference/esp/pbuf.rst

@@ -112,7 +112,8 @@ After concating *2 pbufs* together, reference counter of second is still set to
 An example code showing proper usage of concat operation:
 
 .. literalinclude:: ../../examples_src/pbuf_cat.c
-	:language: c
+    :language: c
+    :caption: Packet buffer concat example
 
 Chain operation
 ***************
@@ -135,7 +136,8 @@ After chainin *2 pbufs* together, reference counter of second is increased by ``
 An example code showing proper usage of chain operation:
 
 .. literalinclude:: ../../examples_src/pbuf_chain.c
-	:language: c
+    :language: c
+    :caption: Packet buffer chain example
 
 Extract pbuf data
 *****************
@@ -147,5 +149,6 @@ An example code showing proper reading of any *pbuf*:
 
 .. literalinclude:: ../../examples_src/pbuf_extract.c
 	:language: c
+    :caption: Packet buffer data extraction
 
 .. doxygengroup:: ESP_PBUF

docs/api-reference/esp/sntp.rst

@@ -8,5 +8,6 @@ It is support through middleware API calls for configuring servers and reading a
 
 .. literalinclude:: ../../../snippets/sntp.c
     :language: c
+    :caption: Minimum SNTP example
 
 .. doxygengroup:: ESP_SNTP

docs/get-started/index.rst

@@ -66,4 +66,5 @@ This file shall be named ``esp_config.h`` and its default template looks like th
     Check :ref:`api_esp_config` section for possible configuration settings
 
 .. literalinclude:: ../../esp_at_lib/src/include/esp/esp_config_template.h
-    :language: c
+    :language: c
+    :caption: Config file template

docs/user-manual/blocking-nonblocking.rst

@@ -24,6 +24,7 @@ Example code:
 
 .. literalinclude:: ../examples_src/command_blocking.c
 	:language: c
+    :caption: Blocking command example
 
 Non-blocking mode
 ^^^^^^^^^^^^^^^^^
@@ -39,6 +40,7 @@ Example code:
 
 .. literalinclude:: ../examples_src/command_nonblocking.c
 	:language: c
+    :caption: Non-blocking command example
 
 .. warning::
 	When using non-blocking API calls, do not use local variables as parameter. 
@@ -48,6 +50,7 @@ Example of a bad code:
 
 .. literalinclude:: ../examples_src/command_nonblocking_bad.c
 	:language: c
+    :caption: Example of bad usage of non-blocking command
 
 .. toctree::
     :maxdepth: 2

docs/user-manual/events-cb-fn.rst

@@ -49,6 +49,7 @@ custom, event function.
 
 .. literalinclude:: ../../esp_at_lib/src/api/esp_netconn.c
     :language: c
+    :caption: Netconn API module actual implementation
 
 Connection specific event
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -67,6 +68,7 @@ Connection events callback function is set for ``2`` cases:
 
 .. literalinclude:: ../../snippets/client.c
     :language: c
+    :caption: An example of client with its dedicated event callback function
 
 API call event
 ^^^^^^^^^^^^^^
@@ -87,6 +89,7 @@ used to distinguis domain name (when multiple domains are to be resolved).
 
 .. literalinclude:: ../../snippets/dns.c
     :language: c
+    :caption: Simple example for API call event, using DNS module
 
 .. toctree::
     :maxdepth: 2

docs/user-manual/porting-guide.rst

@@ -40,7 +40,8 @@ Notes:
 * It sets *send* and *reset* callback functions for *ESP-AT* library
 
 .. literalinclude:: ../../esp_at_lib/src/system/esp_ll_win32.c
-	:language: c
+    :language: c
+    :caption: Actual implementation of low-level driver for WIN32
 
 Example: Low-level driver for STM32
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -56,25 +57,30 @@ Notes:
 * It sets *send* and *reset* callback functions for *ESP-AT* library
 
 .. literalinclude:: ../../esp_at_lib/src/system/esp_ll_stm32.c
-	:language: c
+    :language: c
+    :caption: Actual implementation of low-level driver for STM32
 
 Example: System functions for WIN32
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. literalinclude:: ../../esp_at_lib/src/include/system/esp_sys_win32.h
-  :language: c
+    :language: c
+    :caption: Actual header implementation of system functions for WIN32
 
 .. literalinclude:: ../../esp_at_lib/src/system/esp_sys_win32.c
-  :language: c
+    :language: c
+    :caption: Actual implementation of system functions for WIN32
 
 Example: System functions for CMSIS-OS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. literalinclude:: ../../esp_at_lib/src/include/system/esp_sys_cmsis_os.h
-  :language: c
+    :language: c
+    :caption: Actual header implementation of system functions for CMSIS-OS based operating systems
 
 .. literalinclude:: ../../esp_at_lib/src/system/esp_sys_cmsis_os.c
-  :language: c
+    :language: c
+    :caption: Actual implementation of system functions for CMSIS-OS based operating systems
 
 .. toctree::
     :maxdepth: 2