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
|
||||
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.
|
||||
* 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.
|
||||
|
Loading…
x
Reference in New Issue
Block a user