alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-20 00:36:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

doc: Documenting Code clean up

Browse Source
This commit is contained in:
Krzysztof 2016-11-16 20:13:18 +01:00 committed by Ivan Grokhotkov
parent fa3e4103ab
commit 4e9e8f52ac
2 changed files with 57 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/_static/doc-code-documentation-inline.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

19
docs/documenting-code.rst
View File

@ -56,17 +56,17 @@ When writing code for this repository, please follow guidelines below.
:align: center :align: center
:alt: Sample void function documented inline and after rendering :alt: Sample void function documented inline and after rendering
5. When documenting members of a ``struct``, ``typedef`` or ``enum``, place specific comment like below after each member. 5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
.. image:: _static/doc-code-member.png .. image:: _static/doc-code-member.png
:align: center :align: center
:alt: Sample of member documentation inline and after rendering :alt: Sample of member documentation inline and after rendering
6. To provide well formatted lists, break the line after command (like ``@return`` in example below). 6. To provide well formatted lists, break the line after command (like ``@return`` in example below).
.. code-block:: c ::
...
* *
* @return * @return
* - ESP_OK if erase operation was successful * - ESP_OK if erase operation was successful
@ -75,7 +75,6 @@ When writing code for this repository, please follow guidelines below.
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - other error codes from the underlying storage driver * - other error codes from the underlying storage driver
* *
...
7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``. 7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``.
@ -86,9 +85,8 @@ There is couple of tips, how you can make your documentation even better and mor
1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. 1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands.
.. code-block:: c ::
...
* *
* @code{c} * @code{c}
* // Example of using nvs_get_i32: * // Example of using nvs_get_i32:
@ -99,33 +97,28 @@ There is couple of tips, how you can make your documentation even better and mor
* // have its default value. * // have its default value.
* @endcode * @endcode
* *
...
The code snippet should be enclosed in a comment block of the function that it illustrates. The code snippet should be enclosed in a comment block of the function that it illustrates.
2. To highlight some important information use command ``@attention`` or ``@note``. 2. To highlight some important information use command ``@attention`` or ``@note``.
.. code-block:: c ::
...
* *
* @attention * @attention
* 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode * 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
* 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect. * 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
* *
...
Above example also shows how to use a numbered list. Above example also shows how to use a numbered list.
3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. 3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.
.. code-block:: c ::
...
* *
* [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf) * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
* *
...
.. note:: .. note::