docs: updated documentation.md with more details

Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
Mihai Tudor Panu 2015-03-06 17:45:02 -08:00
parent afd560ccdc
commit f0dd5f9530

View File

@ -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 <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:
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 <chip-id>
* @library <lib-name>
* @name <component-name>
* @category <component-category>
* @manufacturer <component-man>
* @kit <component-kit>
* @connection <connection-type>
*
* @brief Short class/sensor description
*
* Then add a longer
* description here.
*
* @ingroup <name> (<addl group>)
* @image html <name.jpeg>
* @snippet <name.cxx> Interesting
* @image html <component-img.jpeg>
* @snippet <example-name.cxx> 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.
- `<chip-id>` Usually the chip number used by the sensor. When this is not
available or relevant, use a unique descriptor that makes sense. *Mandatory*
- `<lib-name>` When adding to an existing library this needs to match that
library's "@defgroup", otherwise this is generally the same as chip id.
*Mandatory*
- `<component-name>` A short name for your sensor, can include manufacturer
name. *Mandatory*
- `<component-category>` Mention one or more categories the sensor fits in. Can
be 'other'. *Mandatory*
- `<component-man>` Sensor manufacturer. Can be 'generic'. *Mandatory*
- `<component-kit>` Specifies if the sensor is part of a kit. *Optional*
- `<connection-type>` 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 <lib-name> libupm-<lib-name>
* @ingroup <manufacturer> <connection> <category> (<kit>)
*/
@endverbatim
```
In "@defgroup" use the same `<lib-name>` 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.