From f0dd5f95301b5a4f9ccf7c0cf2b547e9584f71f1 Mon Sep 17 00:00:00 2001 From: Mihai Tudor Panu Date: Fri, 6 Mar 2015 17:45:02 -0800 Subject: [PATCH] docs: updated documentation.md with more details Signed-off-by: Mihai Tudor Panu --- docs/documentation.md | 108 +++++++++++++++++++++++++++--------------- 1 file changed, 69 insertions(+), 39 deletions(-) diff --git a/docs/documentation.md b/docs/documentation.md index 6ba8f3f7..19264141 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -4,63 +4,69 @@ 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: +- If you don't add documentation, the code review will take very long and + your contribution could be rejected. - 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 /** */ +- 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. +####The sensor block -Here's how this looks (disregard the "@verbatim" tags in your actual code): - -``` -@verbatim -/** - * @brief Short description for entire library - * @defgroup - * @ingroup () - */ -@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: +This is added just before your class definition and has mandatory fields. For +single sensor libraries, this block will actually follow immediately after the +library block. If you have multiple physical sensors, add this to every one. +Here's an example (disregard the "@verbatim" tags in your actual code): ``` @verbatim /** + * @sensor + * @library + * @name + * @category + * @manufacturer + * @kit + * @connection + * * @brief Short class/sensor description + * + * Then add a longer + * description here. * - * Then add a longer - * description here. - * - * @ingroup () - * @image html - * @snippet Interesting + * @image html + * @snippet Interesting */ @endverbatim ``` -Libraries with multiple sensors can add specific "@ingroup" tags here, but make -sure that the first one is the name specified in the library "@defgroup" tag. -Also, add this block to every sensor. An example of such a library for -reference is our libupm-i2clcd, which acts as a driver for multiple I2C LCDs. +- `` Usually the chip number used by the sensor. When this is not + available or relevant, use a unique descriptor that makes sense. *Mandatory* +- `` When adding to an existing library this needs to match that + library's "@defgroup", otherwise this is generally the same as chip id. + *Mandatory* +- `` A short name for your sensor, can include manufacturer + name. *Mandatory* +- `` Mention one or more categories the sensor fits in. Can + be 'other'. *Mandatory* +- `` Sensor manufacturer. Can be 'generic'. *Mandatory* +- `` Specifies if the sensor is part of a kit. *Optional* +- `` Specifies how does the sensor connect to the board + *Mandatory* + +Existing groups that can be used for the manufacturer, connection, category and +kit tags are found in the src/upm.h file. Optionally, a small representative image can be placed in the "docs/images" -subfolder. **Please do not use existing, copyrighted images with your sensors!** +subfolder and linked with the "@image" tag. +**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: +Tags use this format (in "example-name.cxx"): ``` @verbatim @@ -72,7 +78,31 @@ Tags use this format: @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. + +####The library block + +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. + +You should end up with something like this: + +``` +@verbatim +/** + * @brief Short description for entire library + * + * Optional longer description. + * + * @defgroup libupm- + * @ingroup () + */ +@endverbatim +``` + +In "@defgroup" use the same `` used in the sensor block. Multiple +sensors can be added to the same library this way. +For "@ingroup" add the same values as in the sensor block for manufacturer, +category, connection type and kit. If you have multiple classes or sensors +per library, only use the "@ingroup" tags that are common for all of them.