Home | History | Annotate | Download | only in docs 
      1 Writing sensor documentation                        {#documentation}
      2 =====================
      3 
      4 It is highly encouraged to provide at least some basic documentation for the
      5 sensors that you want to add to UPM:
      6 
      7 - If you don't add documentation, the code review will take very long and 
      8   your contribution could be rejected.
      9 - Try to have no warnings in doxygen, this is generally fairly easy.
     10 - Have the specific sensor manufacturer/model & version that you used, if you
     11   support multiple versions please list.
     12 - Simple comments do not need full stops.
     13 - Stick to <80 chars per line even in comments.
     14 - No text is allowed on the same line as the start or end of a comment /** */.
     15 
     16 ####The sensor block
     17 
     18 This is added just before the class declaration in your header(.h) file and has 
     19 mandatory fields. For single sensor libraries, this block will actually
     20 follow immediately after the library block. If you have multiple physical
     21 sensors, add this to every one.
     22 Here's an example (disregard the "@verbatim" tags in your actual code):
     23 
     24 ```
     25 @verbatim
     26 /**
     27  * @library <lib-name>
     28  * @sensor <chip-id>
     29  * @comname <component-name>
     30  * @altname <alt-name>
     31  * @altid <alt-id>
     32  * @type <component-category>
     33  * @man <component-manufacturer>
     34  * @web <component-weblinks>
     35  * @con <connection-type>
     36  * @kit <component-kit>
     37  *
     38  * @brief Short class/sensor description
     39  * 
     40  *   Then add a longer
     41  *   description here.
     42  *
     43  * @image html <component-img.jpeg>
     44  * @snippet <example-name.cxx> Interesting
     45  */
     46 @endverbatim
     47 ```
     48 
     49 - `<lib-name>` When adding to an existing library this needs to match that
     50   library's "@defgroup", otherwise this is a new library name, generally the
     51   same as chip id. *Mandatory*
     52 - `<chip-id>` Usually the chip number used by the sensor. When this is not
     53   available or relevant, use a unique descriptor that makes sense. *Mandatory*
     54 - `<component-name>` A short name for your sensor, can include manufacturer
     55   name. *Mandatory*
     56 - `<alt-name>` Alternative names that your sensor driver might have. *Optional*
     57 - `<alt-id>` Alternative chip-ids that your sensor driver supports. *Optional*
     58 - `<component-category>` Mention one or more categories the sensor fits in. Can
     59   be 'other'. *Mandatory*
     60 - `<component-manufacturer>` Sensor manufacturer. Can be 'generic'. *Mandatory*
     61 - `<component-weblinks>` Links to vendors or data-sheets. *Optional*
     62 - `<connection-type>` Specifies how does the sensor connect to the board
     63   *Mandatory*
     64 - `<component-kit>` Specifies if the sensor is part of a kit. *Optional*
     65 
     66 Existing groups that can be used for the manufacturer, connection, category and
     67 kit tags are found in the src/upm.h file.
     68 
     69 Optionally, a small representative image can be placed in the "docs/images"
     70 subfolder and linked with the "@image" tag.
     71 **Please do not use existing, copyrighted images with your sensors!**
     72 
     73 The example should have an 'Interesting' section which will be highlighted as
     74 a code sample in doxygen. Everything in between such tags will show up in the
     75 class documentation when "@snippet" is added at the end of a class docstring.
     76 Tags use this format (in "example-name.cxx"):
     77 
     78 ```
     79 @verbatim
     80  //! [Interesting]
     81 
     82     ...example code here...
     83 
     84  //! [Interesting]
     85 @endverbatim
     86 ```
     87 
     88 For more examples take a look at the existing headers in our github repository.
     89 
     90 ####The library block
     91 
     92 New libraries must have the "@brief", "@defgroup" and "@ingroup" tags in one
     93 block. This usually follows the namespace and it is common to have one sensor
     94 per library.
     95 
     96 You should end up with something like this:
     97 
     98 ```
     99 @verbatim
    100 /**
    101  * @brief Short description for entire library
    102  *
    103  * Optional longer description.
    104  *
    105  * @defgroup <lib-name> libupm-<lib-name>
    106  * @ingroup <manufacturer> <connection> <category> (<kit>)
    107  */
    108 @endverbatim
    109 ```
    110 
    111 In "@defgroup" use the same `<lib-name>` used in the sensor block. Multiple
    112 sensors can be added to the same library this way.
    113 For "@ingroup" add the same values as in the sensor block for manufacturer,
    114 category, connection type and kit. If you have multiple classes or sensors
    115 per library, only use the "@ingroup" tags that are common for all of them.
    116