granicus.if.org Git - esp-idf/blob - docs/documenting-code.rst

   1 Documenting Code
   2 ================
   3
   4 The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation.
   5
   6 Introduction
   7 ------------
   8
   9 When documenting code for this repository, please follow `Doxygen style <http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock>`_. You are doing it by inserting special commands, for instance ``@param``, into standard comments blocks, for example:
  10
  11 ::
  12
  13   /**
  14    * @param ratio this is oxygen to air ratio
  15    */
  16
  17 Doxygen is phrasing the code, extracting the commands together with subsequent text, and building documentation out of it.
  18
  19 Typical 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
  25 Doxygen 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 reach and very well organized `Doxygen Manual <http://www.stack.nl/~dimitri/doxygen/manual/index.html>`_.
  26
  27 Why we need it?
  28 ---------------
  29
  30 The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx <http://www.sphinx-doc.org/>`_ and `Breathe <https://breathe.readthedocs.io/>`_ to aid preparation and automatic updates of API documentation when the code changes.
  31
  32 With these tools the above piece of code renders like below:
  33
  34 .. image:: _static/doc-code-documentation-rendered.png
  35    :align: center
  36    :alt: Sample inline code after rendering
  37
  38 Go for it!
  39 ----------
  40
  41 When writing code for this repository, please follow guidelines below.
  42
  43 1. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information on purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
  44
  45 2. Documentation of function should describe what this function does. If it accepts input parameters and returns some value, all of them should be explained.
  46
  47 3. 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.
  48
  49   .. image:: _static/doc-code-function.png
  50      :align: center
  51      :alt: Sample function documented inline and after rendering
  52
  53 4. If function has void input or does not return any value, then skip ``@param`` or ``@return``
  54
  55   .. image:: _static/doc-code-void-function.png
  56      :align: center
  57      :alt: Sample void function documented inline and after rendering
  58
  59 5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
  60
  61   .. image:: _static/doc-code-member.png
  62      :align: center
  63      :alt: Sample of member documentation inline and after rendering
  64
  65
  66 6. To provide well formatted lists, break the line after command (like ``@return`` in example below).
  67
  68   ::
  69
  70     *
  71     * @return
  72     *    - ESP_OK if erase operation was successful
  73     *    - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
  74     *    - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
  75     *    - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
  76     *    - other error codes from the underlying storage driver
  77     *
  78
  79 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``.
  80
  81 Go one extra mile
  82 -----------------
  83
  84 There is couple of tips, how you can make your documentation even better and more useful to the reader.
  85
  86 1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands.
  87
  88   ::
  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
 103 2. To highlight some important information use command ``@attention`` or ``@note``.
 104
 105   ::
 106
 107     *
 108     * @attention
 109     *     1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
 110     *     2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
 111     *
 112
 113   Above example also shows how to use a numbered list.
 114
 115 3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.
 116
 117   ::
 118
 119     *
 120     * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
 121     *
 122
 123 .. note::
 124
 125    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.
 126
 127 5. Prepare one or more complete code examples together with description. Place them in a separate file ``example.rst`` in the same directory as the API header files. If directory contains header files for different APIs, then the file name should be ``apiname-example.rst``.
 128
 129 Put it all together
 130 -------------------
 131
 132 Once all the above steps are complete, follow instruction in :doc:`api/template` and create a single file, that will merge all individual pieces of prepared documentation. Finally add a link to this file to respective ``.. toctree::`` in ``index.rst`` file located in ``/docs`` folder.
 133
 134 OK, but I am new to Sphinx!
 135 ---------------------------
 136
 137 1. No worries. All the software you need is well documented. It is also open source and free. Start by checking `Sphinx <http://www.sphinx-doc.org/>`_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html>`_.
 138 2. Check the source files of this documentation to understand what is behind of what you see now on the screen. Sources are maintained on GitHub in `espressif/esp-idf`_ repository in :idf:`docs` folder. You can go directly to the source file of this page by scrolling up and clicking the link in the top right corner. When on GitHub, see what's really inside, open source files by clicking ``Raw`` button.
 139 3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so:
 140
 141   * Install `Sphinx <http://www.sphinx-doc.org/>`_, `Breathe <https://breathe.readthedocs.io/>`_ and `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ to build it locally. You would need a Linux machine for that.
 142   * Set up an account on `Read the Docs <https://readthedocs.org/>`_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great.
 143
 144 Wrap up
 145 -------
 146
 147 We love good code that is doing cool things.
 148 We love it even better, if it is well documented, so we can quickly make it run and also do the cool things.
 149
 150 Go ahead, contribute your code and documentation!
 151
 152 .. _espressif/esp-idf: https://github.com/espressif/esp-idf/