1Documenting Code
2================
3
4:link_to_translation:`zh_CN:[中文]`
5
6The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation.
7
8Introduction
9------------
10
11When documenting code for this repository, please follow `Doxygen style <http://doxygen.nl/manual/docblocks.html#specialblock>`_. You are doing it by inserting special commands, for instance ``@param``, into standard comments blocks, for example: ::
12
13    /**
14     * @param ratio this is oxygen to air ratio
15     */
16
17Doxygen is phrasing the code, extracting the commands together with subsequent text, and building documentation out of it.
18
19Typical comment block, that contains documentation of a function, looks like below.
20
21.. image:: ../../_static/doc-code-documentation-inline.png
22    :align: center
23    :alt: Sample inline code documentation
24
25Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data rich and very well organized `Doxygen Manual <http://doxygen.nl/manual/index.html>`_.
26
27
28Why we need it?
29---------------
30
31The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx`_ and `Breathe`_ to aid preparation and automatic updates of API documentation when the code changes.
32
33With these tools the above piece of code renders like below:
34
35.. image:: ../../_static/doc-code-documentation-rendered.png
36    :align: center
37    :alt: Sample inline code after rendering
38
39
40Go for it!
41----------
42
43When writing code for this repository, please follow guidelines below.
44
451. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information about purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
46
472. Documentation of function should describe what this function does. If it accepts input parameters and returns some value, all of them should be explained.
48
493. Do not add a data type before parameter or any other characters besides spaces. All spaces and line breaks are compressed into a single space. If you like to break a line, then break it twice.
50
51    .. image:: ../../_static/doc-code-function.png
52        :align: center
53        :alt: Sample function documented inline and after rendering
54
554. If function has void input or does not return any value, then skip ``@param`` or ``@return``
56
57    .. image:: ../../_static/doc-code-void-function.png
58        :align: center
59        :alt: Sample void function documented inline and after rendering
60
615. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
62
63    .. image:: ../../_static/doc-code-member.png
64        :align: center
65        :alt: Sample of member documentation inline and after rendering
66
676. To provide well formatted lists, break the line after command (like ``@return`` in example below). ::
68
69    *
70    * @return
71    *    - ESP_OK if erase operation was successful
72    *    - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
73    *    - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
74    *    - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
75    *    - other error codes from the underlying storage driver
76    *
77
787. Overview of functionality of documented header file, or group of files that make a library, should be placed in a separate ``README.rst`` file of the same directory. If this directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``.
79
80
81Go one extra mile
82-----------------
83
84Here are a couple of tips on how you can make your documentation even better and more useful to the reader and writer.
85
86When writing codes, please follow the guidelines below:
87
881. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. ::
89
90    *
91    * @code{c}
92    * // Example of using nvs_get_i32:
93    * int32_t max_buffer_size = 4096; // default value
94    * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
95    * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
96    * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
97    * // have its default value.
98    * @endcode
99    *
100
101   The code snippet should be enclosed in a comment block of the function that it illustrates.
102
1032. To highlight some important information use command ``@attention`` or ``@note``. ::
104
105    *
106    * @attention
107    *     1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
108    *     2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
109    *
110
111   Above example also shows how to use a numbered list.
112
1133. To provide common description to a group of similar functions, enclose them using ``/**@{*/`` and ``/**@}*/`` markup commands::
114
115    /**@{*/
116    /**
117     * @brief common description of similar functions
118     *
119     */
120    void  first_similar_function (void);
121    void second_similar_function (void);
122    /**@}*/
123
124   For practical example see :component_file:`nvs_flash/include/nvs.h`.
125
1264. You may want to go even further and skip some code like repetitive defines or enumerations. In such case, enclose the code within ``/** @cond */`` and ``/** @endcond */`` commands. Example of such implementation is provided in :component_file:`driver/include/driver/gpio.h`.
127
1285. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
129
130    *
131    * [{IDF_TARGET_NAME} Technical Reference Manual]({IDF_TARGET_TRM_EN_URL})
132    *
133
134.. note::
135
136    Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
137
1386. Prepare one or more complete code examples together with description. Place description to a separate file ``README.md`` in specific folder of :idf:`examples` directory.
139
140Standardize Document Format
141-------------------------------
142
143When it comes to text, please follow guidelines below to provide well formatted Markdown (.md) or reST (.rst) documents.
144
1451. Please ensure that one paragraph is written in one line. Don't break lines like below. Breaking lines to enhance readability is only suitable for writing codes. To make the text easier to read, it is recommended to place an empty line to separate the paragraph.
146
147    .. figure:: ../../_static/doc-format1-recommend.png
148        :align: center
149        :scale: 30%
150        :alt: One line for one paragraph - recommend (click to enlarge)
151
152        One line for one paragraph (click to enlarge)
153
154    .. figure:: ../../_static/doc-format2-notrecommend.png
155        :align: center
156        :scale: 30%
157        :alt: One line for one paragraph - not recommend (click to enlarge)
158
159        No line breaks within the same paragraph (click to enlarge)
160
1612. Please make the line number of CN and EN documents consistent like below. The benefit of this approach is that it can save time for both writers and translators. When non-bilingual writers need to update text, they only need to update the same line in the corresponding CN or EN document. For translators, if documents are updated in English, then translators can quickly locate where to update in the corresponding CN document later. Besides, by comparing the total number of lines in EN and CN documents, you can quickly find out whether the CN version lags behind the EN version.
162
163    .. figure:: ../../_static/doc-format3-recommend.png
164        :align: center
165        :scale: 50%
166        :alt: Keep the line number for EN and CN files consistent (click to enlarge)
167
168        Keep the line number for EN and CN documents consistent (click to enlarge)
169
170Building Documentation
171----------------------
172The documentation is built with the `esp-docs` Python package, which is a wrapper around `Sphinx <https://www.sphinx-doc.org/>`_
173
174To install it simply do::
175
176    pip install esp-docs
177
178After a successful install then the documentation can be built from the docs folder with::
179
180    build-docs build
181
182or for specific target and language with::
183
184    build-docs -t esp32 -l en build
185
186For more in-depth documentation about `esp-docs` features please see the `esp-doc` documentation.
187
188Wrap up
189-------
190
191We love good code that is doing cool things.
192We love it even better, if it is well documented, so we can quickly make it run and also do the cool things.
193
194Go ahead, contribute your code and documentation!
195
196
197Related Documents
198-----------------
199
200* :doc:`../api-reference/template`
201
202
203.. _espressif/esp-idf: https://github.com/espressif/esp-idf/
204
205.. _interactive shell: http://interactive.blockdiag.com/?compression=deflate&src=eJxlUMFOwzAMvecrrO3aITYQQirlAIIzEseJQ5q4TUSIq8TVGIh_J2m7jbKc7Ge_5_dSO1Lv2soWvoVYgieNoMh7VGzJR9FJtugZ7lYQ0UcKEbYNOY36rRQHZHUPT68vV5tceGLbWCUzPfeaFFMoBZzecVc56vWwJFnWMmJ59CCZg617xpOFbTSyw0pmvT_HJ7hxtFNGBr6wvuu5SCkchcrZ1vAeXZomznh5YgTqfcpR02cBO6vZVDeXBRjMjKEcFRbLh8f18-Z2UUBDnqP9wmp9ncRmSSfND2ldGo2h_zse407g0Mxc1q7HzJ3-4jzYYTJjtQH3iSV-fgFzx50J
206
207.. _Breathe: https://breathe.readthedocs.io
208