mirror of
https://github.com/eclipse/upm.git
synced 2025-03-15 04:57:30 +03:00
docs: updated documentation.md with more details
Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
parent
afd560ccdc
commit
f0dd5f9530
@ -4,63 +4,69 @@ Writing sensor documentation {#documentation}
|
|||||||
It is highly encouraged to provide at least some basic documentation for the
|
It is highly encouraged to provide at least some basic documentation for the
|
||||||
sensors that you want to add to UPM:
|
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.
|
- Try to have no warnings in doxygen, this is generally fairly easy.
|
||||||
- Have the specific sensor manufacturer/model & version that you used, if you
|
- Have the specific sensor manufacturer/model & version that you used, if you
|
||||||
support multiple versions please list.
|
support multiple versions please list.
|
||||||
- Simple comments do not need full stops
|
- Simple comments do not need full stops.
|
||||||
- Stick to <80 chars per line even in comments
|
- 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 /** */
|
- 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
|
####The sensor block
|
||||||
block. This usually follows the namespace and it is common to have one sensor
|
|
||||||
per library.
|
|
||||||
|
|
||||||
Here's how this looks (disregard the "@verbatim" tags in your actual code):
|
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.
|
||||||
@verbatim
|
Here's an example (disregard the "@verbatim" tags in your actual code):
|
||||||
/**
|
|
||||||
* @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
|
@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
|
* @brief Short class/sensor description
|
||||||
|
*
|
||||||
|
* Then add a longer
|
||||||
|
* description here.
|
||||||
*
|
*
|
||||||
* Then add a longer
|
* @image html <component-img.jpeg>
|
||||||
* description here.
|
* @snippet <example-name.cxx> Interesting
|
||||||
*
|
|
||||||
* @ingroup <name> (<addl group>)
|
|
||||||
* @image html <name.jpeg>
|
|
||||||
* @snippet <name.cxx> Interesting
|
|
||||||
*/
|
*/
|
||||||
@endverbatim
|
@endverbatim
|
||||||
```
|
```
|
||||||
|
|
||||||
Libraries with multiple sensors can add specific "@ingroup" tags here, but make
|
- `<chip-id>` Usually the chip number used by the sensor. When this is not
|
||||||
sure that the first one is the name specified in the library "@defgroup" tag.
|
available or relevant, use a unique descriptor that makes sense. *Mandatory*
|
||||||
Also, add this block to every sensor. An example of such a library for
|
- `<lib-name>` When adding to an existing library this needs to match that
|
||||||
reference is our libupm-i2clcd, which acts as a driver for multiple I2C LCDs.
|
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"
|
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
|
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
|
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.
|
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
|
@verbatim
|
||||||
@ -72,7 +78,31 @@ Tags use this format:
|
|||||||
@endverbatim
|
@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.
|
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.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user