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>

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