Chapter 6. Contributions Guide
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - 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
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.
Go one extra mile
Here are a couple of tips on how you can make your documentation even better and more useful to the reader and
writer.
When writing codes, please follow the guidelines below:
1. Add code snippets to illustrate implementation. To do so, enclose snippet using @code{c} and @endcode
commands.
*
* @code{c}
* // Example of using nvs_get_i32:
* int32_t max_buffer_size = 4096; // default value
* esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
* assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
* // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
* // have its default value.
* @endcode
*
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.
*
* @attention
* 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.
*
Above example also shows how to use a numbered list.
3. To provide common description to a group of similar functions, enclose them using /**@{*/ and /**@}*/
markup commands:
/**@{*/
/**
* @brief common description of similar functions
*
*/
void first_similar_function (void);
void second_similar_function (void);
/**@}*/
For practical example see nvs_flash/include/nvs.h.
4. 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 imple-
mentation is provided in driver/include/driver/gpio.h.
5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.
Espressif Systems 1579
Submit Document Feedback
Release v4.4
To Next Page
Loading...