Template¶
Note
INSTRUCTIONS
- Use this file as a template to document API.
- Change the file name to the name of the header file that represents documented API.
- Include respective files with descriptions from the API folder using
..include::
- README.rst
- example.rst
- Optionally provide description right in this file.
- Once done, remove all instructions like this one and any superfluous headers.
Overview¶
Note
INSTRUCTIONS
- Provide overview where and how this API may be used.
- Where applicable include code snippets to illustrate functionality of particular functions.
- To distinguish between sections, use the following heading levels:
#
with overline, for parts*
with overline, for chapters=
, for sections-
, for subsections^
, for subsubsections"
, for paragraphs
Application Example¶
Note
INSTRUCTIONS
- Prepare one or more practical examples to demonstrate functionality of this API.
- Each example should follow pattern of projects located in
esp-idf/examples/
folder. - Place example in this folder complete with
README.md
file. - Provide overview of demonstrated functionality in
README.md
. - With good overview reader should be able to understand what example does without opening the source code.
- Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
- Include flow diagram and screenshots of application output if applicable.
- Finally add in this section synopsis of each example together with link to respective folder in
esp-idf/examples/
.
API Reference¶
Note
INSTRUCTIONS
- Specify the names of header files used to generate this reference. Each name should be linked to the source on espressif/esp-idf repository.
- Provide list of API members divided into sections.
- Use corresponding
.. doxygen..
directives, so member documentation is auto updated.
- Data Structures -
.. doxygenstruct::
together with:members:
- Macros -
.. doxygendefine::
- Type Definitions -
.. doxygentypedef::
- Enumerations -
.. doxygenenum::
- Functions -
.. doxygenfunction::
See Breathe documentation for additional information.
- Once done remove superfluous headers.
- When changes are committed and documentation is build, check how this section rendered. Correct annotations in respective header files, if required.
Header Files¶
- path/header-file.h
Data Structures¶
.. doxygenstruct:: name_of_structure
:members:
Macros¶
.. doxygendefine:: name_of_macro
Type Definitions¶
.. doxygentypedef:: name_of_type
Enumerations¶
.. doxygenenum:: name_of_enumeration
Functions¶
.. doxygenfunction:: name_of_function