- 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
- Optionally provide description right in this file.
- Once done, remove all instructions like this one and any superfluous headers.
- 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
- Prepare one or more practical examples to demonstrate functionality of this API.
- Each example should follow pattern of projects located in
- Place example in this folder complete with
- Provide overview of demonstrated functionality in
- 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
- 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
- Macros -
- Type Definitions -
- Enumerations -
- Functions -
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.
.. doxygenstruct:: name_of_structure :members:
.. doxygendefine:: name_of_macro
.. doxygentypedef:: name_of_type
.. doxygenenum:: name_of_enumeration
.. doxygenfunction:: name_of_function