docs: created new documentation.md

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

README.md

@@ -45,6 +45,8 @@ Before you begin development, take a look at our @ref naming [conventions](docs/
 
 Also, please read the guidelines for @ref contributions [to UPM](docs/contributions.md).
 
+Don't forget to check the @ref documentation [section](docs/documentation.md).
+
 Make sure you add yourself as an author on every new code file submitted.
 If you are providing a fix with significant changes, feel free to add yourself
 as a contributor. Signing-off your commits is mandatory.

docs/contributions.md

@@ -2,35 +2,20 @@ Contributing a module                         {#contributions}
 =====================
 
 Here are the rules of contribution:
-- Your module must have an example that builds against your UPM library
-- Commits must have a sign-off line by everyone who reviewed them
-- Commits must be named <file/module>: Some decent description
+- Your new module must have an example that builds against your UPM library.
+- Commits must have a sign-off line by everyone who reviewed them.
+- **Commits must be named <file/module>: Some decent description.**
 - You must license your module under a FOSS license. The recommended license
   is MIT but any permissive license is fine. Please consider that people using
   UPM may want to write proprietary programs with your sensors so we like to
   avoid GPL. (LGPL is fine). If your license is not MIT please include a
-  LICENSE file in src/mymodule/
+  LICENSE file in src/mymodule/.
 - Please test your module builds before contributing and make sure it works on
   the latest version of mraa. If you tested on a specific board/platform please
   tell us what this was in your PR.
 - Try not to break master. In any commit.
-- Attempt to have some decent API documentation below are the explicit rules on documentation:
-
-Documentation
-=============
-
-- 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
-- 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 /** */
-- All classes should have a "@brief" and a "@snippet"
-
-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 the following is put at the end of a class docstring
-as show above.
+- Attempt to have some decent API documentation as described in the the @ref
+  documentation [guide](documentation.md).
 
 Code signing
 ============

docs/documentation.md

@@ -0,0 +1,77 @@
+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:
+
+- 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 /** */
+
+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.
+
+Here's how this looks:
+
+```
+@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:
+
+```
+@verbatim
+/**
+ * @brief Short class/sensor description
+ *
+ * Then add a longer
+ * description here.
+ *
+ * @ingroup <name> (<addl group>)
+ * @image html <name.jpeg>
+ * @snippet <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. An example of such a library for reference is our libupm-i2clcd.
+
+Optionally, a small representative image can be placed in the "docs/images"
+subfolder. **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:
+
+```
+@verbatim
+ //! [Interesting]
+
+    ...example code here...
+
+ //! [Interesting]
+@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.