upm/docs/documentation.md

Writing sensor documentation {#documentation}

It is highly encouraged to provide at least some basic documentation for the sensors that you want to add to UPM:

• Try to have no warnings in doxygen, this is generally fairly easy.
• Have the specific sensor manufacturer/model & version that you used, if you support multiple versions please list.
• Simple comments do not need full stops
• Stick to <80 chars per line even in comments
• No text is allowed on the same line as the start or end of a comment /** */

New libraries must have the “@brief”, “@defgroup” and “@ingroup” tags in one block. This usually follows the namespace and it is common to have one sensor per library.

Here’s how this looks:

@verbatim
/**
 * @brief Short description for entire library
 * @defgroup <name> <libupm-name>
 * @ingroup <manufacturer> <connection type> <sensor category> (<addl group>)
 */
@endverbatim

If you have multiple classes or sensors per library, only use the “@ingroup” tags that are common for all of them.

All classes should then have a “@brief”, “@ingroup” and “@snippet”. For single sensor libraries this block can follow immediately after the one above like in this example:

@verbatim
/**
 * @brief Short class/sensor description
 *
 * Then add a longer
 * description here.
 *
 * @ingroup <name> (<addl group>)
 * @image html <name.jpeg>
 * @snippet <name.cxx> Interesting
 */
@endverbatim

Libraries with multiple sensors can add specific “@ingroup” tags here, but make sure that the first one is the “” specified in the library “@defgroup” tag. An example of such a library for reference is our libupm-i2clcd.

Optionally, a small representative image can be placed in the “docs/images” subfolder. Please do not use existing, copyrighted images with your sensors!

The example should have an ‘Interesting’ section which will be highlighted as a code sample in doxygen. Everything in between such tags will show up in the class documentation when “@snippet” is added at the end of a class docstring. Tags use this format:

@verbatim
 //! [Interesting]

    ...example code here...

 //! [Interesting]
@endverbatim

Existing groups that can be used for the manufacturer, connection and category tags are found in the src/upm.h file.

For more examples take a look at the existing headers in our github repository.