docs: Add docs/ folder with in depth topics as well as DoxygenLayout.xml file

* C headers now have @briefs and include examples
* Examples have altered 'Interesting' Sections

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

Doxyfile.in

@@ -99,7 +99,7 @@ BRIEF_MEMBER_DESC      = YES
 # brief descriptions will be completely suppressed.
 # The default value is: YES.
 
-REPEAT_BRIEF           = YES
+REPEAT_BRIEF           = NO
 
 # This tag implements a quasi-intelligent brief description abbreviator that is
 # used to form the text in various listings. Each string in this list, if found
@@ -129,6 +129,8 @@ ABBREVIATE_BRIEF       = "The $name class" \
 
 ALWAYS_DETAILED_SEC    = NO
 
+DETAILS_AT_TOP         = YES
+
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those
 # members were ordinary class members. Constructors, destructors and assignment
@@ -510,7 +512,7 @@ HIDE_SCOPE_NAMES       = YES
 # the files that are included by a file in the documentation of that file.
 # The default value is: YES.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 # grouped member an include statement to the documentation, telling the reader
@@ -536,7 +538,7 @@ INLINE_INFO            = YES
 # name. If set to NO the members will appear in declaration order.
 # The default value is: YES.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 # descriptions of file, namespace and class members alphabetically by member
@@ -671,7 +673,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = 
+LAYOUT_FILE            = @CMAKE_CURRENT_SOURCE_DIR@/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -753,7 +755,10 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/api/ @CMAKE_CURRENT_SOURCE_DIR@/README.md
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/api/ \
+                         @CMAKE_CURRENT_SOURCE_DIR@/README.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/include/ \
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -863,7 +868,8 @@ EXCLUDE_SYMBOLS        =
 # command).
 
 EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/examples/ \
-                         @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/
+                         @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/ \
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -2206,7 +2212,7 @@ INCLUDE_GRAPH          = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the CALL_GRAPH tag is set to YES then doxygen will generate a call
 # dependency graph for every global function or class method.

DoxygenLayout.xml

@@ -0,0 +1,194 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.8.7 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="modules" visible="yes" title="" intro=""/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="">
+      <tab type="filelist" visible="yes" title="" intro=""/>
+      <tab type="globals" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="examples" visible="yes" title="" intro=""/>  
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="no"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <detaileddescription title="API Description"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <classes visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <functions title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <inlineclasses title=""/>
+      <functions title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <variables title=""/>
+    </memberdef>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>

README.md

@@ -16,37 +16,24 @@ classes directly wrap the C API and provide a near 1:1 mapping of
 functionality.
 
 <center>
-C API Modules        | C++ API Classes
+| C API Modules       | C++ API Classes             |
-:-------------------:|:-------------------:
+|:-------------------:|:---------------------------:|
- @ref gpio.h "gpio"  | @ref maa::Gpio "Gpio class"
+| @ref gpio.h "gpio"  | @ref maa::Gpio "Gpio class" |
- @ref i2c.h "i2c"    | @ref maa::I2c "I2c class"
+| @ref i2c.h "i2c"    | @ref maa::I2c "I2c class"   |
- @ref aio.h "aio"    | @ref maa::Aio "Aio class"
+| @ref aio.h "aio"    | @ref maa::Aio "Aio class"   |
- @ref pwm.h "pwm"    | @ref maa::Pwm "Pwm class"
+| @ref pwm.h "pwm"    | @ref maa::Pwm "Pwm class"   |
- @ref spi.h "spi"    | @ref maa::Spi "Spi class"
+| @ref spi.h "spi"    | @ref maa::Spi "Spi class"   |
- @ref maa.h "maa"    | @ref maa.h "maa"
+| @ref maa.h "maa"    | @ref maa.h "maa"            |
 </center>
 
 ### Hello Maa
 @snippet hellomaa.c Interesting
 
-### Basic GPIO
-@snippet gpio_read6.c Interesting
-
-### Basic PWM
-@snippet cycle-pwm3.c Interesting
-
-### Basic I2C
-@snippet analogin_a0.c Interesting
-
-### Basic AIO
-@snippet analogin_a0.c Interesting
-
-### Basic SPI
-@snippet spi_mcp4261.c Interesting
-
 ## Supported platforms
 
-- Galileo (Fab D)
+Specific platform information for supported platforms is documented here:
+
+- @ref galileorevd
 
 ### ENV RECOMENDATIONS
 
@@ -60,15 +47,11 @@ cmake, libm and pthreads are technically required to compile.
 
 ## COMPILING
 
-mkdir build/
+More information on compiling is @ref building page
-cmake -i ..
-make
 
-## DEVELOPMENT
+## CONTRIBUTING
 
-Please fork the code on github and then send pull requests. Please avoid merges
+Please see the @ref contributing page
-in your forks. I will also accept patches sent in git style with signoffs to
-brendan.le.foll@intel.com
 
 ## API Changelog
 

api/aio.h

@@ -25,8 +25,12 @@
 #pragma once
 /** @file
  *
- * This file defines the aio (analog in) interface for libmaa
+ * @brief Analog input/output
  *
+ * AIO is the anlog input & output interface to libmaa. It is used to read or
+ * set the voltage applied to an AIO pin.
+ *
+ * @snippet analogin_a0.c Interesting
  */
 
 #ifdef __cplusplus
@@ -44,7 +48,8 @@ extern "C" {
 #define ADC_SUPPORTED_RESOLUTION_BITS   (10)
 
 /**
- * Opaque pointer definition to the internal struct _aio
+ * Opaque pointer definition to the internal struct _aio. This context refers
+ * to one single AIO pin on the board.
  */
 typedef struct _aio* maa_aio_context;
 

api/gpio.h

@@ -26,8 +26,15 @@
 
 /** @file
  *
- * This file defines the gpio interface for libmaa
+ * @brief General Purpose IO
  *
+ * GPIO is the General Purpose IO interface to libmaa. It's features depends on
+ * the board type used, it can use gpiolibs (exported via a kernel module
+ * through sysfs), or memory mapped IO via a /dev/uio device or /dev/mem
+ * depending again on the board configuratio, or memory mapped IO via a
+ * /dev/uio device or /dev/mem depending again on the board configuration.
+ *
+ * @snippet gpio_read6.c Interesting
  */
 
 #ifdef __cplusplus

api/i2c.h

@@ -26,8 +26,15 @@
 
 /** @file
  *
- * This file defines the i2c interface for libmaa
+ * @brief Inter-Integrated Circuit
  *
+ * This file defines the i2c/Iic interface for libmaa. A context represents a
+ * bus and that bus may contain multiple addresses or i2c slaves. It is
+ * considered best practice to make sure the address is correct before doing
+ * any calls on i2c, in case another application or even thread changed the
+ * addres on that bus. Multiple instances of the same bus can exist.
+ *
+ * @snippet i2c_HMC5883L.c Interesting
  */
 
 #ifdef __cplusplus

api/pwm.h

@@ -26,8 +26,14 @@
 
 /** @file
  *
- * This file defines the pwm interface for libmaa
+ * @brief Pulse Width Modulation module
  *
+ * PWM is the Pulse Width Modulation interface to libmaa. It allows the
+ * generation of a signal on a pin. Some boards may have higher or lower levels
+ * of resolution so make sure you check the board & pin you are using before
+ * hand.
+ *
+ * @snippet cycle-pwm3.c Interesting
  */
 
 #ifdef __cplusplus

api/spi.h

@@ -25,9 +25,12 @@
 #pragma once
 
 /** @file
+ *
+ * @brief System Packet Interface
  *
  * This file defines the spi interface for libmaa
  *
+ * @snippet spi_mcp4261.c Interesting
  */
 
 #ifdef __cplusplus

docs/building.md

@@ -0,0 +1,27 @@
+Building libmaa                         {#building}
+===============
+
+libmaa uses cmake in order to make compilation relatively painless. Cmake runs
+build out of tree so the recommended way is to clone from git and make a build/ directory.
+
+~~~~~~~~~~~~~{.sh}
+mkdir build
+cd build
+cmake ..
+make
+~~~~~~~~~~~~~
+
+Our cmake configure has a number of options, `cmake -i` will ask you all sorts
+of interesting questions, you can disable swig modules, build documentation
+etc...
+
+Few recommended options:
+Changing install path from /usr/local to /usr
+-DCMAKE_INSTALL_PREFIX:PATH=/usr
+
+Building debug build:
+-DCMAKE_BUILD_TYPE=DEBUG
+
+Using clang instead of gcc:
+ -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang
+

docs/contributing.md

@@ -0,0 +1,17 @@
+Contributing to libmaa                           {#contributing} 
+======================
+
+libmaa is an opensource project and we are actively looking for people to help
+with:
+
+- Writing platform supports for all types of embedded boards running linux
+- People to write cool samples
+- People to extend the functionality
+
+The recommended method to contribute is to fork on github, and then send pull
+requests to the main project. Questions can be also be asked and issues raised
+on github.
+
+If you'd rather not use github you are more than welcome to send git formatted
+patches to brendan.le.foll@intel.com.
+

docs/galileorevd.md

@@ -0,0 +1,10 @@
+Galileo Rev D                            {#galileorevd}
+=============
+
+Galileo is a microcontroller board based on the Intel® Quark SoC X1000
+Application Processor, a 32-bit Intel Pentium-class system on a chip.
+
+The rev D board has the following limitations in libmaa:
+
+- gpio register access via /dev/uio is limited to pin2 and 3
+- gpio interupts will only work on GPIO_EDGE_BOTH

examples/analogin_a0.c

@@ -23,7 +23,7 @@
  */
 
 #include <unistd.h>
-
+//! [Interesting]
 #include "aio.h"
 
 int main ()
@@ -31,7 +31,6 @@ int main ()
     maa_aio_context adc_a0;
     uint16_t adc_value = 0;
 
-//! [Interesting]
     adc_a0 = maa_aio_init(0);
     if (adc_a0 == NULL) {
         return 1;
@@ -43,7 +42,7 @@ int main ()
     }
 
     maa_aio_close(adc_a0);
-//! [Interesting]
 
     return MAA_SUCCESS;
 }
+//! [Interesting]

examples/hellomaa.c

@@ -23,14 +23,13 @@
  */
 
 #include "stdio.h"
-
+//! [Interesting]
 #include "maa.h"
 
 int
 main(int argc, char **argv)
 {
-//! [Interesting]
     fprintf(stdout, "hello maa\n Version: %s\n", maa_get_version());
     return 0;
-//! [Interesting]
 }
+//! [Interesting]