docs: updated documentation.md with more details

Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>

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 <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.