Merge branch 'doc/pr103_cleanup' into 'master'

Documentation cleanup

From @kryzchb, github pull request #103

See merge request !214

CONTRIBUTING.rst

@@ -15,7 +15,9 @@ Before sending us a Pull Request, please consider this list of points:
 
 * Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it.
 
-* Does any new code conform to the esp-idf Style Guide? (Style Guide currently pending).
+* Does any new code conform to the esp-idf :doc:`Style Guide <style-guide>`?
+
+* Does the code documentation follow requirements in :doc:`documenting-code`?
 
 * Is the code adequately commented for people to understand how it is structured?
 

docs/Doxyfile

@@ -1,3 +1,18 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow, 
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://www.stack.nl/~dimitri/doxygen/manual/config.html
+
+
 PROJECT_NAME = "ESP32 Programming Guide"
 
 INPUT = ../components/esp32/include/esp_wifi.h \
@@ -10,12 +25,16 @@ INPUT = ../components/esp32/include/esp_wifi.h \
 	../components/esp32/include/esp_int_wdt.h \
 	../components/esp32/include/esp_task_wdt.h
 
+## Get warnings for functions that have no documentation for their parameters or return value 
+##
 WARN_NO_PARAMDOC = YES
 
-RECURSIVE		= NO
+## Do not complain about not having dot
-CASE_SENSE_NAMES 	= NO
+##
-EXTRACT_ALL		= NO
+HAVE_DOT = NO
 
+## Generate XML that is required for Breathe
+##
 GENERATE_XML = YES
 XML_OUTPUT = xml
 
@@ -25,5 +44,9 @@ GENERATE_LATEX		= NO
 GENERATE_MAN		= YES
 GENERATE_RTF		= NO
 
+## Skip distracting progress messages
+##
+QUIET = YES
+## Log warnings in a file for further review
+##
 WARN_LOGFILE = "doxygen-warning-log.txt"
-

docs/api/bt.rst

@@ -9,15 +9,19 @@ Overview
 Application Example
 -------------------
 
-`Instructions`_
+Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
 
-API Reference
+`05_ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/05_ble_adv/main/app_bt.c>`_ 
--------------
+
+  This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising.
 
 `Instructions`_
 
 .. _Instructions: template.html
 
+API Reference
+-------------
+
 Header Files
 ^^^^^^^^^^^^
 
@@ -35,4 +39,3 @@ Functions
 .. doxygenfunction:: API_vhci_host_register_callback
 .. doxygenfunction:: API_vhci_host_send_packet
 .. doxygenfunction:: bt_controller_init
-

docs/api/ledc.rst

@@ -27,7 +27,10 @@ Data Structures
 ^^^^^^^^^^^^^^^
 
 .. doxygenstruct:: ledc_channel_config_t
+   :members:
+
 .. doxygenstruct:: ledc_timer_config_t
+   :members:
 
 Macros
 ^^^^^^

docs/api/nvs_flash.rst

@@ -5,8 +5,23 @@ Application Example
 
 Two examples are provided in ESP-IDF examples directory:
 
-- `07_nvs_rw_value <https://github.com/espressif/esp-idf/tree/master/examples/07_nvs_rw_value>`_ demostrates how to read and write integer values
+`07_nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/07_nvs_rw_value/main/nvs_rw_value.c>`_
-- `08_nvs_rw_blob <https://github.com/espressif/esp-idf/tree/master/examples/08_nvs_rw_blob>`_ demostrates how to read and write variable length binary values
+
+  Demonstrates how to read and write a single integer value using NVS.
+
+  The value holds the number of ESP32 module restarts. Since it is written to NVS, the value is preserved between restarts.
+
+  Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
+
+`08_nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/08_nvs_rw_blob/main/nvs_rw_blob.c>`_
+
+  Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
+
+    * value - tracks number of ESP32 module soft and hard restarts.
+    * blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. New run time is added to the table on each manually triggered soft restart and written back to NVS. Triggering is done by pulling down GPIO0.
+
+  Example also shows how to implement diagnostics if read / write operation was successful.
+
 
 API Reference
 -------------

docs/api/vfs.rst

@@ -25,6 +25,7 @@ Structures
 ^^^^^^^^^^
 
 .. doxygenstruct:: esp_vfs_t
+   :members:
 
 Functions
 ^^^^^^^^^

docs/build_system.rst

@@ -57,6 +57,7 @@ Example Project
 ---------------
 
 An example project directory tree might look like this::
+
     - myProject/
                  - Makefile
                  - sdkconfig
@@ -66,11 +67,11 @@ An example project directory tree might look like this::
                                - component2/ - component.mk
                                              - Kconfig
                                              - src1.c
-                                             - include/
+                                             - include/ - component2.h
-                                                    - component2.h
                  - main/       - src1.c
                                - src2.c
                                - component.mk
+
                  - build/
 
 This example "myProject" contains the following elements:
@@ -101,6 +102,7 @@ Minimal Example Makefile
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
+
    PROJECT_NAME := myProject
    
    include $(IDF_PATH)/make/project.mk
@@ -135,7 +137,8 @@ Minimal Component Makefile
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set:
-- All source files in the same directory as the makefile (*.c, *.cpp, *.S) will be compiled into the component library
+
+- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.S``) will be compiled into the component library
 - A sub-directory "include" will be added to the global include search path for all other components.
 - The component library will be linked into the project app.
 
@@ -209,8 +212,8 @@ The following variables can be set inside ``component.mk`` to control the build
   ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not
   expanded relative to the component directory.
 - ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
-  component directory, which will be searched for source files (*.cpp,
+  component directory, which will be searched for source files (``*.cpp``,
-  *.c, *.S). Defaults to '.', ie the component directory
+  ``*.c``, ``*.S``). Defaults to '.', ie the component directory
   itself. Override this to specify a different list of directories
   which contain source files.
 - ``COMPONENT_OBJS``: Object files to compile. Default value is a .o
@@ -366,12 +369,14 @@ The configuration system can be used to conditionally compile some files
 depending on the options selected in ``make menuconfig``:
 
 ``Kconfig``::
+
     config FOO_ENABLE_BAR
         bool "Enable the BAR feature."
         help
             This enables the BAR feature of the FOO component.
 
 ``component.mk``::
+
     COMPONENT_OBJS := foo_a.o foo_b.o
 
     ifdef CONFIG_FOO_BAR

docs/documenting-code.rst

@@ -40,33 +40,33 @@ Go for it!
 
 When writing code for this repository, please follow guidelines below.
 
-  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.
+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.
 
-  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.
+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.
 
-  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.
+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.
 
   .. image:: _static/doc-code-function.png
      :align: center
      :alt: Sample function documented inline and after rendering
 
-  4. If function has void input or does not return any value, then skip ``@param`` or ``@return``
+4. If function has void input or does not return any value, then skip ``@param`` or ``@return``
 
   .. image:: _static/doc-code-void-function.png
      :align: center
      :alt: Sample void function documented inline and after rendering
  
-  5. When documenting members of a ``struct``, ``typedef`` or ``enum``, place specific comment like below after each member.
+5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
 
   .. image:: _static/doc-code-member.png
      :align: center
      :alt: Sample of member documentation inline and after rendering
 
-  6. To provide well formatted lists, break the line after command (like ``@return`` in example below).
 
-    .. code-block:: c
+6. To provide well formatted lists, break the line after command (like ``@return`` in example below).
+
+  ::
 
-      ...
     *
     * @return
     *    - ESP_OK if erase operation was successful
@@ -75,20 +75,18 @@ When writing code for this repository, please follow guidelines below.
     *    - 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 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``.
+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``.
 
 Go one extra mile
 -----------------
 
 There is couple of tips, how you can make your documentation even better and more useful to the reader.
 
-  1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. 
+1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. 
 
-    .. code-block:: c
+  ::
 
-      ...
     *
     * @code{c}
     * // Example of using nvs_get_i32:
@@ -99,39 +97,34 @@ There is couple of tips, how you can make your documentation even better and mor
     * // 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``.
+2. To highlight some important information use command ``@attention`` or ``@note``.
 
-    .. code-block:: c
+  ::
 
-      ...
     *
     * @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. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.
+3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.
 
-    .. code-block:: c
+  ::
 
-      ...
     *
     * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
     *
-      ...
 
-  .. note::
+.. note::
 
    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.
 
-  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``.
+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``.
 
 Put it all together
 -------------------

docs/index.rst

@@ -5,6 +5,9 @@ ESP32 Programming Guide
 
    Until ESP-IDF release 1.0, this documentation is a draft. It is incomplete and may have mistakes. Please mind your step!
 
+Documentation adressed to developers of applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ by `Espressif <https://espressif.com/>`_ using `esp-idf <https://github.com/espressif/esp-idf>`_.
+
+
 Contents:
 
 .. toctree::
@@ -41,7 +44,7 @@ Contents:
    1. System - TBA
      1.1. Fundamentals of multiprocessor programming with FreeRTOS - TBA
      1.2. Application startup flow - TBA
-     1.3. Flash encryption and secure boot: how they work and APIs - TBA
+     1.3. Flash encryption and secure boot: how they work and APIs
      1.4. Lower Power Coprocessor - TBA
      1.5. Watchdogs <api/wdts>
      1.6. ...
@@ -61,7 +64,7 @@ Contents:
      6.1. GPIO
      6.2. ADC - TBA
      6.3. DAC - TBA
-     6.4. UART - TBA
+     6.4. UART
      6.5. I2C - TBA
      6.6. I2S - TBA
      6.7. SPI - TBA
@@ -78,9 +81,9 @@ Contents:
      7.3. Touch Sensor - TBA
    8. Protocols - TBA
    9. Components
-     9.1. Logging <api/log>
+     9.1. Logging
-     9.2  Non-Volatile Storage <api/nvs_flash>
+     9.2  Non-Volatile Storage
-     9.3  Virtual Filesystem <api/vfs>
+     9.3  Virtual Filesystem
      9.3. Http sever - TBA
    10. Applications - TBA
    ..
@@ -129,11 +132,9 @@ Contents:
 
    COPYRIGHT
 
-.. About - TBA
-
  
 Indices
-=======
+-------
 
 * :ref:`genindex`
 * :ref:`search`

docs/security/secure-boot.rst

@@ -27,18 +27,18 @@ This is a high level overview of the secure boot process. Step by step instructi
 
 2. Secure Boot Configuration includes "Secure boot signing key", which is a file path. This file is a ECDSA public/private key pair in a PEM format file.
 
-2. The software bootloader image is built by esp-idf with secure boot support enabled and the public key (signature verification) portion of the secure boot signing key compiled in. This software bootloader image is flashed at offset 0x1000.
+3. The software bootloader image is built by esp-idf with secure boot support enabled and the public key (signature verification) portion of the secure boot signing key compiled in. This software bootloader image is flashed at offset 0x1000.
 
-3. On first boot, the software bootloader follows the following process to enable secure boot:
+4. On first boot, the software bootloader follows the following process to enable secure boot:
 
    - Hardware secure boot support generates a device secure bootloader key (generated via hardware RNG, then stored read/write protected in efuse), and a secure digest. The digest is derived from the key, an IV, and the bootloader image contents.
    - The secure digest is flashed at offset 0x0 in the flash.
    - Depending on Secure Boot Configuration, efuses are burned to disable JTAG and the ROM BASIC interpreter (it is strongly recommended these options are turned on.)
    - Bootloader permanently enables secure boot by burning the ABS_DONE_0 efuse. The software bootloader then becomes protected (the chip will only boot a bootloader image if the digest matches.)
 
-4. On subsequent boots the ROM bootloader sees that the secure boot efuse is burned, reads the saved digest at 0x0 and uses hardware secure boot support to compare it with a newly calculated digest. If the digest does not match then booting will not continue. The digest and comparison are performed entirely by hardware, and the calculated digest is not readable by software. For technical details see `Hardware Secure Boot Support`.
+5. On subsequent boots the ROM bootloader sees that the secure boot efuse is burned, reads the saved digest at 0x0 and uses hardware secure boot support to compare it with a newly calculated digest. If the digest does not match then booting will not continue. The digest and comparison are performed entirely by hardware, and the calculated digest is not readable by software. For technical details see `Hardware Secure Boot Support`.
 
-5. When running in secure boot mode, the software bootloader uses the secure boot signing key (the public key of which is embedded in the bootloader itself, and therefore validated as part of the bootloader) to verify the signature appended to all subsequent partition tables and app images before they are booted.
+6. When running in secure boot mode, the software bootloader uses the secure boot signing key (the public key of which is embedded in the bootloader itself, and therefore validated as part of the bootloader) to verify the signature appended to all subsequent partition tables and app images before they are booted.
 
 Keys
 ----