From: Brendan Le Foll <brendan.le.foll@intel.com>
Date: Fri, 30 May 2014 16:10:52 +0000 (+0100)
Subject: api: add proper doxygen comments to C++ headers and normalise doc
X-Git-Tag: v0.2.8~10
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5b191ab6cdf92106f6190955cc2d279c39e1992c;p=contrib%2Fmraa.git

api: add proper doxygen comments to C++ headers and normalise doc

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

diff --git a/api/aio.h b/api/aio.h
index 4513e24..9cd55f6 100644
--- a/api/aio.h
+++ b/api/aio.h
@@ -23,8 +23,8 @@
  */
 
 #pragma once
-/** @file
- *
+/**
+ * @file
  * @brief Analog input/output
  *
  * AIO is the anlog input & output interface to libmaa. It is used to read or
@@ -53,33 +53,27 @@ extern "C" {
  */
 typedef struct _aio* maa_aio_context;
 
-/** Initialise an Analog input device, connected to the specified pin
- *
- * @param aio_channel channel number to read ADC inputs
+/**
+ * Initialise an Analog input device, connected to the specified pin
  *
- * @returns pointer to maa_aio_context structure after initialisation of Analog
- * input pin successfully, else returns null.
+ * @param pin Channel number to read ADC inputs
+ * @returns aio context or NULL
  */
-maa_aio_context maa_aio_init(unsigned int aio_channel);
+maa_aio_context maa_aio_init(unsigned int pin);
 
-/** Read the input voltage, represented as an unsigned short in the range [0x0,
- * 0xFFFF]
- *
- * @param dev -  pointer to maa_aio_context structure  initialised by
- * maa_aio_init()
+/**
+ * Read the input voltage
  *
- * @returns 16-bit unsigned integer representing the current input voltage,
- * normalised to a 16-bit value
+ * @param dev The AIO context
+ * @returns The current input voltage, normalised to a 16-bit value
  */
 uint16_t maa_aio_read(maa_aio_context dev);
 
-/** Close the analog input context
- * - Will free the memory for the context.
- *
- * @param dev -  pointer to maa_aio_context structure  initialised by
- * maa_aio_init()
+/**
+ * Close the analog input context, this will free the memory for the context
  *
- * @return maa_result_t - result type.
+ * @param dev The AIO context
+ * @return Result of operation
  */
 maa_result_t maa_aio_close(maa_aio_context dev);
 
diff --git a/api/aio.hpp b/api/aio.hpp
index f882b6c..dd145d7 100644
--- a/api/aio.hpp
+++ b/api/aio.hpp
@@ -24,27 +24,43 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the aio C++ interface for libmaa
- *
- */
-
 #include "aio.h"
 
 namespace maa {
 
+/**
+ * @brief C++ API to Analog IO
+ *
+ * This file defines the aio C++ interface for libmaa
+ *
+ * @snippet examples/c++/AioA0.cpp Interesting
+ */
 class Aio {
     public:
+        /**
+         * Aio Constructor, takes a pin number which will map directly to the
+         * board number
+         *
+         * @param pin channel number to read ADC inputs
+         */
         Aio(unsigned int pin) {
             m_aio = maa_aio_init(pin);
         }
+        /**
+         * Aio destructor
+         */
         ~Aio() {
             maa_aio_close(m_aio);
         }
+        /**
+         * Read a value from the AIO pin. Note this value can never be outside
+         * of the bounds of an unsigned short
+         *
+         * @returns The current input voltage, normalised to a 16-bit value
+         */
         int read() {
-	    // Use basic types to make swig code generation simpler
-	    return (int) maa_aio_read(m_aio);
+            // Use basic types to make swig code generation simpler
+            return (int) maa_aio_read(m_aio);
         }
     private:
         maa_aio_context m_aio;
diff --git a/api/gpio.h b/api/gpio.h
index d3ced85..bc99981 100644
--- a/api/gpio.h
+++ b/api/gpio.h
@@ -24,15 +24,15 @@
 
 #pragma once
 
-/** @file
- *
+/**
+ * @file
  * @brief General Purpose IO
  *
- * GPIO is the General Purpose IO interface to libmaa. It's features depends on
+ * 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.
+ * /dev/uio device or /dev/mem depending again on the board configuration
  *
  * @snippet gpio_read6.c Interesting
  */
@@ -49,9 +49,6 @@ extern "C" {
 #include <pthread.h>
 
 #include "maa.h"
-/**
- * A strucutre representing a gpio pin.
- */
 
 /**
  * Opaque pointer definition to the internal struct _gpio
@@ -59,7 +56,7 @@ extern "C" {
 typedef struct _gpio* maa_gpio_context;
 
 /**
- * GPIO Output modes
+ * Gpio Output modes
  */
 typedef enum {
     MAA_GPIO_STRONG     = 0, /**< Default. Strong high and low */
@@ -69,124 +66,127 @@ typedef enum {
 } gpio_mode_t;
 
 /**
- * GPIO Direction options.
+ * Gpio Direction options
  */
 typedef enum {
     MAA_GPIO_OUT    = 0, /**< Output. A Mode can also be set */
-    MAA_GPIO_IN     = 1  /**< Input. */
+    MAA_GPIO_IN     = 1  /**< Input */
 } gpio_dir_t;
 
+/**
+ * Gpio Edge types for interupts
+ */
 typedef enum {
-    MAA_GPIO_EDGE_NONE    = 0, /**< No interrupt on GPIO */
+    MAA_GPIO_EDGE_NONE    = 0, /**< No interrupt on Gpio */
     MAA_GPIO_EDGE_BOTH    = 1, /**< Interupt on rising & falling */
     MAA_GPIO_EDGE_RISING  = 2, /**< Interupt on rising only */
     MAA_GPIO_EDGE_FALLING = 3  /**< Interupt on falling only */
 } gpio_edge_t;
 
-/** Initialise gpio_context, based on board number
- *
- *  @param pin pin number read from the board, i.e IO3 is 3.
+/**
+ * Initialise gpio_context, based on board number
  *
- *  @returns maa_gpio_context based on the IO pin
+ *  @param pin Pin number read from the board, i.e IO3 is 3
+ *  @returns gpio context or NULL
  */
 maa_gpio_context maa_gpio_init(int pin);
 
-/** Initialise gpio context without any mapping to a pin.
- * - For more expert users
+/**
+ * Initialise gpio context without any mapping to a pin
  *
  * @param gpiopin gpio pin as listed in SYSFS
- *
- * @return gpio context
+ * @return gpio context or NULL
  */
 maa_gpio_context maa_gpio_init_raw(int gpiopin);
 
-/** Set the edge mode on the gpio
+/**
+ * Set the edge mode on the gpio
  *
- * @param dev The GPIO context
+ * @param dev The Gpio context
  * @param mode The edge mode to set the gpio into
- *
- * @return maa result type.
+ * @return Result of operation
  */
 maa_result_t maa_gpio_edge_mode(maa_gpio_context dev, gpio_edge_t mode);
 
-/** Set an interupt on pin
+/**
+ * Set an interupt on pin
  *
- * @param dev The GPIO context
- * @param mode The edge mode to set the gpio into
+ * @param dev The Gpio context
+ * @param edge The edge mode to set the gpio into
  * @param fptr Function pointer to function to be called when interupt is
  * triggered
- *
- * @return maa result type.
+ * @return Result of operation
  */
-maa_result_t
-maa_gpio_isr(maa_gpio_context dev, gpio_edge_t edge, void (*fptr)(void));
+maa_result_t maa_gpio_isr(maa_gpio_context dev, gpio_edge_t edge, void (*fptr)(void));
 
-/** Stop the current interupt watcher on this GPIO, and set the GPIO edge mode
- * to MAA_GPIO_EDGE_NONE.
- *
- * @param dev The GPIO context.
+/**
+ * Stop the current interupt watcher on this Gpio, and set the Gpio edge mode
+ * to MAA_GPIO_EDGE_NONE
  *
- * @return maa result type.
+ * @param dev The Gpio context
+ * @return Result of operation
  */
-maa_result_t
-maa_gpio_isr_exit(maa_gpio_context dev);
+maa_result_t maa_gpio_isr_exit(maa_gpio_context dev);
 
-/** Set GPIO Output Mode,
- *
- * @param dev The GPIO context
- * @param mode The GPIO Output Mode.
+/**
+ * Set Gpio Output Mode,
  *
- * @return maa result type.
+ * @param dev The Gpio context
+ * @param mode The Gpio Output Mode
+ * @return Result of operation
  */
 maa_result_t maa_gpio_mode(maa_gpio_context dev, gpio_mode_t mode);
 
-/** Set GPIO direction
- *
- * @param dev The GPIO context.
- * @param dir The direction of the GPIO.
+/**
+ * Set Gpio direction
  *
- * @return maa result type.
+ * @param dev The Gpio context
+ * @param dir The direction of the Gpio
+ * @return Result of operation
  */
 maa_result_t maa_gpio_dir(maa_gpio_context dev, gpio_dir_t dir);
 
-/** Close the GPIO context
- * - Will free the memory for the context and unexport the GPIO
- *
- * @param dev the GPIO context
+/**
+ * Close the Gpio context
+ * - Will free the memory for the context and unexport the Gpio
  *
- * @return maa result type.
+ * @param dev The Gpio context
+ * @return Result of operation
  */
 maa_result_t maa_gpio_close(maa_gpio_context dev);
 
-/** Read the GPIO value.
- *
- * @param dev The GPIO context.
+/**
+ * Read the Gpio value.
  *
- * @return the integer value of the GPIO
+ * @param dev The Gpio context
+ * @return Result of operation
  */
 int maa_gpio_read(maa_gpio_context dev);
 
-/** Write to the GPIO Value.
- *
- * @param dev The GPIO context.
- * @param value Integer value to write.
+/**
+ * Write to the Gpio Value.
  *
- * @return maa result type
+ * @param dev The Gpio context
+ * @param value Integer value to write
+ * @return Result of operation
  */
 maa_result_t maa_gpio_write(maa_gpio_context dev, int value);
 
-/** Change ownership of the context.
+/**
+ * Change ownership of the context.
  *
- * @param dev gpio context
- * @param owner does this context own the pin.
+ * @param dev The Gpio context
+ * @param owner Does this context own the pin
+ * @return Result of operation
  */
 maa_result_t maa_gpio_owner(maa_gpio_context dev, maa_boolean_t owner);
 
-/** Enable using memory mapped io instead of sysfs
+/**
+ * Enable using memory mapped io instead of sysfs
  *
- * @param dev gpio context
- * @param mmap use mmap instead of sysfs
- * @return maa_result type
+ * @param dev The Gpio context
+ * @param mmap Use mmap instead of sysfs
+ * @return Result of operation
  */
 maa_result_t maa_gpio_use_mmaped(maa_gpio_context dev, maa_boolean_t mmap);
 
diff --git a/api/gpio.hpp b/api/gpio.hpp
index 8d156b8..1ba84c5 100644
--- a/api/gpio.hpp
+++ b/api/gpio.hpp
@@ -24,38 +24,61 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the gpio C++ interface for libmaa
- *
- */
-
 #include "gpio.h"
 
 namespace maa {
 
 // These enums must match the enums in gpio.h
+
+/**
+ * Gpio Output modes
+ */
 typedef enum {
-    MODE_STRONG = 0,
-    MODE_PULLUP = 1,
-    MODE_PULLDOWN = 2,
-    MODE_HIZ = 3
+    MODE_STRONG   = 0, /**< No interrupt on Gpio */
+    MODE_PULLUP   = 1, /**< Interupt on rising & falling */
+    MODE_PULLDOWN = 2, /**< Interupt on rising only */
+    MODE_HIZ      = 3  /**< Interupt on falling only */
 } Mode;
 
+/**
+ * Gpio Direction options
+ */
 typedef enum {
-    DIR_OUT = 0,
-    DIR_IN = 1
+    DIR_OUT = 0, /**< Output. A Mode can also be set */
+    DIR_IN  = 1  /**< Input */
 } Dir;
 
+/**
+ * Gpio Edge types for interupts
+ */
 typedef enum {
-    EDGE_NONE = 0,
-    EDGE_BOTH = 1,
-    EDGE_RISING = 2,
-    EDGE_FALLING = 3
+    EDGE_NONE    = 0, /**< No interrupt on Gpio */
+    EDGE_BOTH    = 1, /**< Interupt on rising & falling */
+    EDGE_RISING  = 2, /**< Interupt on rising only */
+    EDGE_FALLING = 3  /**< Interupt on falling only */
 } Edge;
 
+/**
+ * @brief C++ API to General Purpose IO
+ *
+ * This file defines the gpio C++ interface for libmaa
+ *
+ * @snippet Blink-IO.cpp Interesting
+ */
 class Gpio {
     public:
+        /**
+         * Instanciates a Gpio object
+         *
+         * @param pin pin number to use
+         * @param owner (optional) Set pin owner, default behaviour is to 'own'
+         * the pin if we exported it. This means we will close it on destruct.
+         * Otherwise it will get left open. This is only valid in sysfs use
+         * cases
+         * @param raw (optional) Raw pins will use gpiolibs pin numbering from
+         * the kernel module. Note that you will not get any muxers set up for
+         * you so this may not always work as expected.
+         */
         Gpio(int pin, bool owner=true, bool raw=false) {
             if (raw)
                 m_gpio = maa_gpio_init_raw(pin);
@@ -64,9 +87,19 @@ class Gpio {
             if (!owner)
                 maa_gpio_owner(m_gpio, 0);
         }
+        /**
+         * Gpio object destructor, this will only unexport the gpio if we where
+         * the owner
+         */
         ~Gpio() {
-            maa_result_t x = maa_gpio_close(m_gpio);
+            maa_gpio_close(m_gpio);
         }
+        /**
+         * Set the edge mode for ISR
+         *
+         * @param mode The edge mode to set
+         * @return Result of operation
+         */
         maa_result_t edge(Edge mode) {
             return maa_gpio_edge_mode(m_gpio, (gpio_edge_t) mode);
         }
@@ -75,23 +108,57 @@ class Gpio {
             return maa_gpio_isr(m_gpio, (gpio_edge_t) mode, (void (*) ()) pyfunc);
         }
 #else
+        /**
+         * Sets a callback to be called when pin value changes
+         *
+         * @return Result of operation
+         */
         maa_result_t isr(Edge mode, void (*fptr)(void)) {
             return maa_gpio_isr(m_gpio, (gpio_edge_t) mode, fptr);
         }
 #endif
+        /**
+         * Exits callback - this call will not kill the isr thread imediatlu
+         * but only when it is out of it's critical section
+         *
+         * @return Result of operation
+         */
         maa_result_t isr_exit() {
             return maa_gpio_isr_exit(m_gpio);
         }
+        /**
+         * Change Gpio mode
+         *
+         * @param mode The mode to change the gpio into
+         * @return Result of operation
+         */
         maa_result_t mode(Mode mode) {
             return maa_gpio_mode(m_gpio, (gpio_mode_t) mode);
         }
+        /**
+         * Change Gpio direction
+         *
+         * @param dir The direction to change the gpio into
+         * @return Result of operation
+         */
         maa_result_t dir(Dir dir) {
             return maa_gpio_dir(m_gpio, (gpio_dir_t) dir);
         }
+        /**
+         * Read value from Gpio
+         *
+         * @return Gpio value
+         */
         int read() {
             return maa_gpio_read(m_gpio);
         }
-        int write(int value) {
+        /**
+         * Write value to Gpio
+         *
+         * @param value Value to write to Gpio
+         * @return Result of operation
+         */
+        maa_result_t write(int value) {
             return maa_gpio_write(m_gpio, value);
         }
     private:
diff --git a/api/i2c.h b/api/i2c.h
index 86c9f2f..214737f 100644
--- a/api/i2c.h
+++ b/api/i2c.h
@@ -24,8 +24,8 @@
 
 #pragma once
 
-/** @file
- *
+/**
+ * @file
  * @brief Inter-Integrated Circuit
  *
  * This file defines the i2c/Iic interface for libmaa. A context represents a
@@ -54,82 +54,84 @@ extern "C" {
  */
 typedef struct _i2c* maa_i2c_context;
 
-/** Initialise i2c context, using board defintions
+/**
+ * Initialise i2c context, using board defintions
  *
  * @param bus i2c bus to use
- * @return maa_i2c_context i2c context ready for other calls.
+ * @return i2c context or NULL
  */
 maa_i2c_context maa_i2c_init(int bus);
 
-/** Initialise i2c context, passing in spi bus to use.
+/**
+ * Initialise i2c context, passing in spi bus to use.
  *
  * @param bus The i2c bus to use i.e. /dev/i2c-2 would be "2"
- * @return maa_i2c_context i2c context ready for other calls.
+ * @return i2c context or NULL
  */
 maa_i2c_context maa_i2c_init_raw(unsigned int bus);
 
-/** Sets the frequency of the i2c context
- *
- *  @param dev the i2c context
- *  @param hz The bus frequency in hertz
+/**
+ * Sets the frequency of the i2c context
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @param hz The bus frequency in hertz
+ * @return Result of operation
  */
 maa_result_t maa_i2c_frequency(maa_i2c_context dev, int hz);
 
-/** Read from an i2c context
- *
- *  @param dev the i2c context
- *  @param data pointer to the byte array to read data in to
- *  @param length max number of bytes to read
+/**
+ * Read from an i2c context
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @param data pointer to the byte array to read data in to
+ * @param length max number of bytes to read
+ * @return Result of operation
  */
 maa_result_t maa_i2c_read(maa_i2c_context dev, uint8_t *data, int length);
 
-/** Read a single byte from the i2c context
- *
- *  @param dev the i2c context
+/**
+ * Read a single byte from the i2c context
  *
- *  @return byte the result of the read or -1 if failed.
+ * @param dev The i2c context
+ * @return The result of the read or -1 if failed
  */
 uint8_t maa_i2c_read_byte(maa_i2c_context dev);
 
-/** Write to an i2c context
- *
- *  @param dev the i2c context
- *  @param data pointer to the byte array to be written
- *  @param length the number of bytes to transmit
+/**
+ * Write to an i2c context
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @param data pointer to the byte array to be written
+ * @param length the number of bytes to transmit
+ * @return Result of operation
  */
 maa_result_t maa_i2c_write(maa_i2c_context dev, const uint8_t *data, int length);
 
-/** Write a single byte to an i2c context
- *
- *  @param dev the i2c context
- *  @data the byte to write
+/**
+ * Write a single byte to an i2c context
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @param data The byte to write
+ * @return Result of operation
  */
 maa_result_t maa_i2c_write_byte(maa_i2c_context dev, const uint8_t data);
 
-/** Sets the i2c context address.
- *
- *  @param dev the i2c context
- *  @param address The address to set for the slave (ignoring the least
- *  signifcant bit). If set to 0, the slave will only respond to the
- *  general call address.
+/**
+ * Sets the i2c context address.
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @param address The address to set for the slave (ignoring the least
+ *   signifcant bit). If set to 0, the slave will only respond to the
+ *   general call address.
+ * @return Result of operation
  */
 maa_result_t maa_i2c_address(maa_i2c_context dev, int address);
 
-/** De-inits an maa_i2c_context device
- *
- *  @param dev the i2c context
+/**
+ * De-inits an maa_i2c_context device
  *
- *  @return maa_result_t the maa result.
+ * @param dev The i2c context
+ * @return Result of operation
  */
 maa_result_t maa_i2c_stop(maa_i2c_context dev);
 
diff --git a/api/i2c.hpp b/api/i2c.hpp
index 4d5f794..eb480aa 100644
--- a/api/i2c.hpp
+++ b/api/i2c.hpp
@@ -24,42 +24,96 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the i2c C++ interface for libmaa
- *
- */
-
 #include "i2c.h"
 
 namespace maa {
 
+/**
+ * @brief C++ API to Inter-Integrated Circuit
+ *
+ * This file defines the I2c C++ interface for libmaa
+ *
+ * @snippet I2c-compass.cpp Interesting
+ */
 class I2c {
     public:
+        /**
+         * Instantiates an i2c bus. Multiple instances of the same bus can
+         * exist and the bus is not guarranteed to be on the correct address
+         * before read/write.
+         *
+         * @param bus The i2c bus to use
+         * @param raw Whether to disable pinmapper for your board
+         */
         I2c(int bus, bool raw=false) {
             if (raw)
                 m_i2c = maa_i2c_init_raw(bus);
             else
                 m_i2c = maa_i2c_init(bus);
         }
+        /**
+         * Closes the I2c Bus used. This does not guarrantee the bus will not
+         * be usable by anyone else or communicates this disconnect to any
+         * slaves.
+         */
         ~I2c() {
             maa_i2c_stop(m_i2c);
         }
+        /**
+         * Sets the i2c Frequency for communication. Your board may not support
+         * the set frequency. Anyone can change this at any time and this will
+         * affect every slave on the bus
+         *
+         * @param hz Frequency to set the bus to in hz
+         * @return Result of operation
+         */
         maa_result_t frequency(int hz) {
             return maa_i2c_frequency(m_i2c, hz);
         }
+        /**
+         * Set the slave to talk to, typically called before every read/write
+         * operation
+         *
+         * @param address Communicate to the i2c slave on this address
+         * @return Result of operation
+         */
         maa_result_t address(int address) {
             return maa_i2c_address(m_i2c, address);
         }
+        /**
+         * Read exactly one byte from the bus
+         *
+         * @return Char read from the bus
+         */
         unsigned char read_byte() {
             return (unsigned char) maa_i2c_read_byte(m_i2c);
         }
+        /**
+         * Read mutliple bytes from the bus
+         *
+         * @param data Buffer to write into
+         * @param length Size of read
+         * @return Result of operation
+         */
         maa_result_t read(unsigned char * data, int length) {
             return maa_i2c_read(m_i2c, data, length);
         }
+        /**
+         * Write one byte to the bus
+         *
+         * @param data Buffer to send on the bus
+         * @param length Size of buffer to send
+         * @return Result of operation
+         */
         maa_result_t write(const unsigned char* data, int length) {
             return maa_i2c_write(m_i2c, data, length);
         }
+        /**
+         * Write multiple bytes to the bus
+         *
+         * @param data The byte to send on the bus
+         * @return Result of operation
+         */
         maa_result_t write_byte(const unsigned char data) {
             return maa_i2c_write_byte(m_i2c, data);
         }
diff --git a/api/maa.h b/api/maa.h
index 0c83c3b..63f7b53 100644
--- a/api/maa.h
+++ b/api/maa.h
@@ -27,7 +27,6 @@
 /** @file
  *
  * This file defines the basic shared values for libmaa
- *
  */
 
 #ifdef __cplusplus
@@ -96,6 +95,7 @@ typedef struct {
     /*@{*/
     unsigned int pin;   /**< Raw GPIO pin id */
     unsigned int value; /**< Raw GPIO value */
+    /*@}*/
 } maa_mux_t;
 
 /**
@@ -179,10 +179,12 @@ typedef struct {
     /*@}*/
 } maa_board_t;
 
-/** Initialise MAA
+/**
+ * Initialise MAA
  *
  * Detects running platform and attempts to use included pinmap
- * @return maa_result_t maa result
+ *
+ * @return Result of operation
  */
 #ifndef SWIG
 // this sets a compiler attribute (supported by GCC & clang) to have maa_init()
@@ -197,17 +199,20 @@ maa_result_t maa_init();
  *
  * The version returned may not be what is expected however it is a reliable
  * number associated with the git tag closest to that version at build time
+ *
  * @return version string from version.h
  */
 const char* maa_get_version();
 
-/** Print a textual representation of the maa_result_t
+/**
+ * Print a textual representation of the maa_result_t
  *
- * @param result the result to print,
+ * @param result the result to print
  */
 void maa_result_print(maa_result_t result);
 
-/** Checks if a pin is able to use the passed in mode.
+/**
+ * Checks if a pin is able to use the passed in mode.
  *
  * @param pin Physical Pin to be checked.
  * @param mode the mode to be tested.
diff --git a/api/pwm.h b/api/pwm.h
index fce45c8..c4f0a2f 100644
--- a/api/pwm.h
+++ b/api/pwm.h
@@ -24,8 +24,8 @@
 
 #pragma once
 
-/** @file
- *
+/**
+ * @file
  * @brief Pulse Width Modulation module
  *
  * PWM is the Pulse Width Modulation interface to libmaa. It allows the
@@ -47,121 +47,124 @@ extern "C" {
 
 typedef struct _pwm* maa_pwm_context;
 
-/** Initialise pwm_context, uses board mapping.
- *
- * @param pin The PWM PIN.
+/**
+ * Initialise pwm_context, uses board mapping
  *
- * @return maa_pwm_context The returned initialised pwm context
+ * @param pin The PWM PIN
+ * @return pwm context or NULL
  */
 maa_pwm_context maa_pwm_init(int pin);
 
-/** Initialise pwm_context, raw mode.
+/**
+ * Initialise pwm_context, raw mode
  *
  * @param chipid The chip inwhich the PWM is under in SYSFS
  * @param pin The PWM PIN.
- *
- * @return maa_pwm_context The returned initialised pwm context
+ * @return pwm context or NULL
  */
 maa_pwm_context maa_pwm_init_raw(int chipid, int pin);
 
-/** Set the ouput duty-cycle percentage, as a float
+/**
+ * Set the ouput duty-cycle percentage, as a float
  *
- * @param pwm The PWM context to use.
+ * @param dev The Pwm context to use
  * @param percentage A floating-point value representing percentage of output.
  *    The value should lie between 0.0f (representing on 0%) and 1.0f
- *    Values above or below this range will be set at either 0.0f or 1.0f.
- *
- * @return maa_result_t the maa result.
+ *    Values above or below this range will be set at either 0.0f or 1.0f
+ * @return Result of operation
  */
-maa_result_t maa_pwm_write(maa_pwm_context pwm, float percentage);
+maa_result_t maa_pwm_write(maa_pwm_context dev, float percentage);
 
-/** Read the ouput duty-cycle percentage, as a float
+/**
+ * Read the ouput duty-cycle percentage, as a float
  *
- * @param pwm The PWM context to use.
+ * @param dev The Pwm context to use
  * @return percentage A floating-point value representing percentage of output.
  *    The value should lie between 0.0f (representing on 0%) and 1.0f
- *    Values above or below this range will be set at either 0.0f or 1.0f.
+ *    Values above or below this range will be set at either 0.0f or 1.0f
  */
-float maa_pwm_read(maa_pwm_context pwm);
+float maa_pwm_read(maa_pwm_context dev);
 
-/** Set the PWM period as seconds represented in a float
- *
- * @param pwm The PWM context to use.
- * @param seconds Peroid represented as a float in seconds.
+/**
+ * Set the PWM period as seconds represented in a float
  *
- * @return maa_result_t the maa result.
+ * @param dev The Pwm context to use
+ * @param seconds Period represented as a float in seconds
+ * @return Result of operation
  */
-maa_result_t maa_pwm_period(maa_pwm_context pwm, float seconds);
+maa_result_t maa_pwm_period(maa_pwm_context dev, float seconds);
 
-/** Set period, milli-oseconds.
- *
- * @param pwm The PWM context to use.
- * @param ms milli-seconds for period.
+/**
+ * Set period, milliseconds.
  *
- * @return maa_result_t the maa result.
+ * @param dev The Pwm context to use
+ * @param ms Milliseconds for period
+ * @return Result of operation
  */
-maa_result_t maa_pwm_period_ms(maa_pwm_context pwm, int ms);
+maa_result_t maa_pwm_period_ms(maa_pwm_context dev, int ms);
 
-/** Set period, microseconds
+/**
+ * Set period, microseconds
  *
- * @param pwm The PWM context to use.
- * @param ns microseconds as period.
- *
- * @return maa_result_t the maa result.
+ * @param dev The Pwm context to use
+ * @param us Microseconds as period
+ * @return Result of operation
  */
-maa_result_t maa_pwm_period_us(maa_pwm_context pwm, int us);
+maa_result_t maa_pwm_period_us(maa_pwm_context dev, int us);
 
-/** Set pulsewidth, As represnted by seconds in a (float).
+/**
+ * Set pulsewidth, As represnted by seconds in a (float)
  *
- * @param pwm The PWM context to use.
+ * @param dev The Pwm context to use
  * @param seconds The duration of a pulse
- *
- * @return maa_result_t the maa result.
+ * @return Result of operation
  */
-maa_result_t maa_pwm_pulsewidth(maa_pwm_context pwm, float seconds);
+maa_result_t maa_pwm_pulsewidth(maa_pwm_context dev, float seconds);
 
-/** Set pulsewidth, milliseconds
- *
- * @param pwm The PWM context to use.
- * @param ms milliseconds for pulsewidth.
+/**
+ * Set pulsewidth, milliseconds
  *
- * @return maa_result_t the maa result.
+ * @param dev The Pwm context to use
+ * @param ms Milliseconds for pulsewidth
+ * @return Result of operation
  */
-maa_result_t maa_pwm_pulsewidth_ms(maa_pwm_context pwm, int ms);
+maa_result_t maa_pwm_pulsewidth_ms(maa_pwm_context dev, int ms);
 
-/** Set pulsewidth, microseconds.
+/**
+ * Set pulsewidth, microseconds
  *
- * @param pwm The PWM context to use.
- * @param us microseconds for pulsewidth.
- *
- * @return maa_result_t the maa result.
+ * @param dev The Pwm context to use
+ * @param us Microseconds for pulsewidth
+ * @return Result of operation
  */
-maa_result_t maa_pwm_pulsewidth_us(maa_pwm_context pwm, int us);
+maa_result_t maa_pwm_pulsewidth_us(maa_pwm_context dev, int us);
 
-/** Set the enable status of the PWM pin. None zero will assume on with output being driven.
+/**
+ * Set the enable status of the PWM pin. None zero will assume on with output being driven.
  *   and 0 will disable the output.
  *
- * @param pwm The PWM context to use.
- * @param enable enable status of pin
- *
- * @return maa_result_t the maa result.
+ * @param dev The pwm context to use
+ * @param enable Toggle status of pin
+ * @return Result of operation.
  */
-maa_result_t maa_pwm_enable(maa_pwm_context pwm, int enable);
+maa_result_t maa_pwm_enable(maa_pwm_context dev, int enable);
 
-/** Change ownership of context
+/**
+ * Change ownership of context
  *
- * @param pwm the context
- * @param owner ownership , 1 to own
+ * @param dev the context
+ * @param owner Ownership boolean
+ * @return Result of operation
  */
-maa_result_t maa_pwm_owner(maa_pwm_context pwm, maa_boolean_t owner);
+maa_result_t maa_pwm_owner(maa_pwm_context dev, maa_boolean_t owner);
 
-/** Close and unexport the PWM pin.
- *
- * @param pwm The PWM context to use.
+/**
+ * Close and unexport the PWM pin
  *
- * @return maa_result_t the maa result.
+ * @param dev The pwm context to use
+ * @return Result of operation
  */
-maa_result_t maa_pwm_close(maa_pwm_context pwm);
+maa_result_t maa_pwm_close(maa_pwm_context dev);
 
 #ifdef __cplusplus
 }
diff --git a/api/pwm.hpp b/api/pwm.hpp
index 2481b63..a897841 100644
--- a/api/pwm.hpp
+++ b/api/pwm.hpp
@@ -24,18 +24,28 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the pwm C++ interface for libmaa
- *
- */
-
 #include "pwm.h"
 
 namespace maa {
 
+/**
+ * @brief C++ API to Pulse Width Modulation
+ *
+ * This file defines the PWM C++ interface for libmaa
+ *
+ * @snippet Pwm3-cycle.cpp Interesting
+ */
 class Pwm {
     public:
+        /**
+         * instanciates a PWM object on a pin
+         *
+         * @param pin the pin number used on your board
+         * @param chipid the pwmchip to use, use only in raw mode
+         * @param owner if you are the owner of the pin the destructor will
+         * unexport the pin from sysfs, default behaviour is you are the owner
+         * if the pinmapper exported it
+         */
         Pwm(int pin, int chipid=-1, bool owner = true) {
             if (chipid == -1)
                 m_pwm = maa_pwm_init(pin);
@@ -44,33 +54,96 @@ class Pwm {
             if (!owner)
                 maa_pwm_owner(m_pwm, 0);
         }
+        /**
+         * Pwm destructor
+         */
         ~Pwm() {
             maa_pwm_close(m_pwm);
         }
+        /**
+         * Set the output duty-cycle percentage, as a float
+         *
+         * @param percentage A floating-point value representing percentage of
+         * output. The value should lie between 0.0f (representing on 0%) and
+         * 1.0f Values above or below this range will be set at either 0.0f or
+         * 1.0f
+         * @return Result of operation
+         */
         maa_result_t write(float percentage) {
             return maa_pwm_write(m_pwm, percentage);
         }
+        /**
+         * Read the ouput duty-cycle percentage, as a float
+         *
+         * @return A floating-point value representing percentage of
+         * output. The value should lie between 0.0f (representing on 0%) and
+         * 1.0f Values above or below this range will be set at either 0.0f or
+         * 1.0f
+         */
         float read() {
             return maa_pwm_read(m_pwm);
         }
+        /**
+         * Set the PWM period as seconds represented in a float
+         *
+         * @param period Period represented as a float in seconds
+         * @return Result of operation
+         */
         maa_result_t period(float period) {
             return maa_pwm_period(m_pwm, period);
         }
+        /**
+         * Set period, milliseconds
+         *
+         * @param ms milliseconds for period
+         * @return Result of operation
+         */
         maa_result_t period_ms(int ms) {
             return maa_pwm_period_ms(m_pwm, ms);
         }
+        /**
+         * Set period, microseconds
+         *
+         * @param us microseconds as period
+         * @return Result of operation
+         */
         maa_result_t period_us(int us) {
             return maa_pwm_period_us(m_pwm, us);
         }
+        /**
+         * Set pulsewidth, As represnted by seconds in a (float)
+         *
+         * @param seconds The duration of a pulse
+         * @return Result of operation
+         */
         maa_result_t pulsewidth(float seconds) {
             return maa_pwm_pulsewidth(m_pwm, seconds);
         }
+        /**
+         * Set pulsewidth, milliseconds
+         *
+         * @param ms milliseconds for pulsewidth
+         * @return Result of operation
+         */
         maa_result_t pulsewidth_ms(int ms) {
             return maa_pwm_pulsewidth_ms(m_pwm, ms);
         }
+        /**
+         * The pulsewidth, microseconds
+         *
+         * @param us microseconds for pulsewidth
+         * @return Result of operation
+         */
         maa_result_t pulsewidth_us(int us) {
             return maa_pwm_pulsewidth_us(m_pwm, us);
         }
+        /**
+         * Set the enable status of the PWM pin. None zero will assume on with
+         * output being driven and 0 will disable the output
+         *
+         * @param enable enable status of pin
+         * @return Result of operation
+         */
         maa_result_t enable(bool enable) {
             if (enable)
                 return maa_pwm_enable(m_pwm, 1);
diff --git a/api/spi.h b/api/spi.h
index a1d7bea..84a3c80 100644
--- a/api/spi.h
+++ b/api/spi.h
@@ -24,8 +24,8 @@
 
 #pragma once
 
-/** @file
- *
+/**
+ * @file
  * @brief System Packet Interface
  *
  * This file defines the spi interface for libmaa
@@ -43,78 +43,76 @@ extern "C" {
 
 #include "maa.h"
 
+/**
+ * Opaque pointer definition to the internal struct _spi
+ */
 typedef struct _spi* maa_spi_context;
 
-/** Initialise SPI_context, uses board mapping. Sets the muxes
+/**
+ * Initialise SPI_context, uses board mapping. Sets the muxes
  *
- * @param bus to use, as listed in platform definition. Normally 0
- * @return maa_spi_context The returned initialised SPI context
+ * @param bus Bus to use, as listed in platform definition, normally 0
+ * @return Spi context or NULL
  */
 maa_spi_context maa_spi_init(int bus);
 
-/** Set the SPI device mode. see spidev
- * 0-3.
- * @param spi the spi device context
- * @param mode the mode. See Linux spidev
+/**
+ * Set the SPI device mode. see spidev 0-3.
  *
- * @return maa_spi_context The returned initialised SPI context
+ * @param dev The Spi context
+ * @param mode The SPI mode, See Linux spidev
+ * @return Spi context or NULL
  */
 maa_result_t maa_spi_mode(maa_spi_context dev,unsigned short mode);
 
 /** Set the SPI device operating clock frequency.
  *
- * @param spi the spid device clock frequency
+ * @param dev the Spi context
  * @param hz the frequency in hz
- *
  * @return maa_spi_context The returned initialised SPI context
  */
 maa_result_t maa_spi_frequency(maa_spi_context dev, int hz);
 
 /** Write Single Byte to the SPI device.
  *
- * @param spi the spid device clock frequency
- * @param data to send
- *
- * @return data received on the miso line.
+ * @param dev The Spi context
+ * @param data Data to send
+ * @return Data received on the miso line
  */
 uint8_t maa_spi_write(maa_spi_context dev, uint8_t data);
 
 /** Write Buffer of bytes to the SPI device.
  *
- * @param spi the spid device clock frequency
+ * @param dev The Spi context
  * @param data to send
  * @param length elements within buffer, Max 4096
- *
- * @return data received on the miso line. Same length as passed in.
+ * @return Data received on the miso line, same length as passed in
  */
 uint8_t* maa_spi_write_buf(maa_spi_context dev, uint8_t* data, int length);
 
 /**
+ * Change the SPI lsb mode
  *
- * @param dev spi context
- * @param lsb. Use least significant bit transmission. 0 for msbi
- *
- * @return maa result of operation
+ * @param dev The Spi context
+ * @param lsb Use least significant bit transmission. 0 for msbi
+ * @return Result of operation
  */
-maa_result_t
-maa_spi_lsbmode(maa_spi_context dev, maa_boolean_t lsb);
+maa_result_t maa_spi_lsbmode(maa_spi_context dev, maa_boolean_t lsb);
 
-/** Set bits per mode on transaction
- * Defaults at 8.
+/**
+ * Set bits per mode on transaction, defaults at 8
  *
- * @param dev spi context
+ * @param dev The Spi context
  * @param bits bits per word
- *
  * @return Result of operation
  */
-maa_result_t
-maa_spi_bit_per_word(maa_spi_context dev, unsigned int bits);
+maa_result_t maa_spi_bit_per_word(maa_spi_context dev, unsigned int bits);
 
-/** De-inits an maa_spi_context device
- *
- *  @param dev the spi context
+/**
+ * De-inits an maa_spi_context device
  *
- *  @return maa_result_t the maa result.
+ * @param dev The Spi context
+ * @return Result of operation
  */
 maa_result_t maa_spi_stop(maa_spi_context dev);
 
diff --git a/api/spi.hpp b/api/spi.hpp
index b5e01b3..a2cc9e9 100644
--- a/api/spi.hpp
+++ b/api/spi.hpp
@@ -24,37 +24,89 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the spi C++ interface for libmaa
- */
-
 #include "spi.h"
 
 namespace maa {
 
+/**
+ * @brief C++ API to System Packet Interface
+ *
+ * This file defines the SPI C++ interface for libmaa
+ *
+ * @snippet Spi-pot.cpp Interesting
+ */
 class Spi {
     public:
+        /**
+         * Initialise SPI object using the board mapping to set muxes
+         *
+         * @param bus to use, as listed in the platform definition, normally 0
+         */
         Spi(int bus) {
             m_spi = maa_spi_init(bus);
         }
+        /**
+         * Closes spi bus
+         */
         ~Spi() {
             maa_spi_stop(m_spi);
         }
+        /**
+         * Set the SPI device mode. see spidev0-3
+         *
+         * @param mode the mode. See Linux spidev doc
+         * @return Result of operation
+         */
         maa_result_t mode(unsigned short mode) {
             return maa_spi_mode(m_spi, mode);
         }
+        /**
+         * Set the SPI device operating clock frequency
+         *
+         * @param hz the frequency to set in hz
+         * @return Result of operation
+         */
         maa_result_t frequency(int hz) {
             return maa_spi_frequency(m_spi, hz);
         }
+        /**
+         * Write single byte to the SPI device
+         *
+         * @param data the byte to send
+         * @return data received on the miso line
+         */
         unsigned char write(uint8_t data) {
             return (unsigned char) maa_spi_write(m_spi, data);
         }
+        /**
+         * Write buffer of bytes to SPI device
+         *
+         * @param data buffer to send
+         * @param length size of buffer to send
+         * @return char* data received on the miso line. Same length as passed in
+         */
         unsigned char* write_buf(uint8_t* data, int length) {
             return (unsigned char*) maa_spi_write_buf(m_spi, data, length);
         }
-    private:
-        maa_spi_context m_spi;
-};
-
+        /**
+         * Change the SPI lsb mode
+         *
+         * @param lsb Use least significant bit transmission - 0 for msbi
+         * @return Result of operation
+         */
+        maa_result_t lsbmode(bool lsb) {
+            return maa_spi_lsbmode(m_spi, (maa_boolean_t) lsb);
+        }
+        /**
+         * Set bits per mode on transaction, default is 8
+         *
+         * @param bits bits per word
+         * @return Result of operation
+         */
+        maa_result_t bit_per_word(unsigned int bits) {
+            return maa_spi_bit_per_word(m_spi, bits);
+        }
+            private:
+                maa_spi_context m_spi;
+        };
 }
diff --git a/examples/c++/AioA0.cpp b/examples/c++/AioA0.cpp
index 2a809d3..cfa3af6 100644
--- a/examples/c++/AioA0.cpp
+++ b/examples/c++/AioA0.cpp
@@ -22,6 +22,7 @@
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+//! [Interesting]
 #include "aio.hpp"
 
 int main ()
@@ -41,3 +42,4 @@ int main ()
 
     return MAA_SUCCESS;
 }
+//! [Interesting]
diff --git a/examples/c++/Blink-IO.cpp b/examples/c++/Blink-IO.cpp
index c06ea6d..c39af75 100644
--- a/examples/c++/Blink-IO.cpp
+++ b/examples/c++/Blink-IO.cpp
@@ -30,7 +30,6 @@
 #include <unistd.h>
 
 #include "gpio.hpp"
-
 #define DEFAULT_IOPIN 8
 
 static int iopin;
@@ -44,7 +43,6 @@ sig_handler(int signo)
         running = -1;
     }
 }
-
 int main (int argc, char **argv)
 {
     if (argc < 2) {
@@ -53,6 +51,10 @@ int main (int argc, char **argv)
     } else {
         iopin = strtol(argv[1], NULL, 10);
     }
+
+    signal(SIGINT, sig_handler);
+
+//! [Interesting]
     maa::Gpio* gpio = new maa::Gpio(iopin);
     if (gpio == NULL) {
         return MAA_ERROR_UNSPECIFIED;
@@ -61,8 +63,6 @@ int main (int argc, char **argv)
     if (response != MAA_SUCCESS)
         maa_result_print((maa_result_t) MAA_SUCCESS);
 
-    signal(SIGINT, sig_handler);
-
     while (running == 0) {
         response = gpio->write(1);
         sleep(1);
@@ -71,4 +71,5 @@ int main (int argc, char **argv)
     }
     delete gpio;
     return response;
+//! [Interesting]
 }
diff --git a/examples/c++/I2c-compass.cpp b/examples/c++/I2c-compass.cpp
index 4dcb587..d30c518 100644
--- a/examples/c++/I2c-compass.cpp
+++ b/examples/c++/I2c-compass.cpp
@@ -93,6 +93,7 @@ sig_handler(int signo)
 
 int main ()
 {
+//! [Interesting]
     maa::I2c* i2c;
     i2c = new maa::I2c(0);
     float direction = 0;
@@ -103,7 +104,7 @@ int main ()
     rx_tx_buf[0] = HMC5883L_CONF_REG_B;
     rx_tx_buf[1] = GA_1_3_REG;
     i2c->write(rx_tx_buf, 2);
-
+//! [Interesting]
     signal(SIGINT, sig_handler);
 
     while (running == 0) {
diff --git a/examples/c++/Pwm3-cycle.cpp b/examples/c++/Pwm3-cycle.cpp
index ea2bfa2..af8f497 100644
--- a/examples/c++/Pwm3-cycle.cpp
+++ b/examples/c++/Pwm3-cycle.cpp
@@ -40,6 +40,8 @@ sig_handler(int signo)
 
 int main ()
 {
+    signal(SIGINT, sig_handler);
+//! [Interesting]
     maa::Pwm* pwm;
 
     pwm = new maa::Pwm(3);
@@ -48,8 +50,6 @@ int main ()
     }
     fprintf(stdout, "Cycling PWM on IO3 (pwm3) \n");
 
-    signal(SIGINT, sig_handler);
-
     float value = 0.0f;
     while (running == 0) {
         value = value + 0.01f;
@@ -60,6 +60,7 @@ int main ()
         }
     }
     delete pwm;
+//! [Interesting]
 
     return MAA_SUCCESS;
 }
diff --git a/examples/c++/Spi-pot.cpp b/examples/c++/Spi-pot.cpp
index 52084ee..57a1264 100644
--- a/examples/c++/Spi-pot.cpp
+++ b/examples/c++/Spi-pot.cpp
@@ -41,12 +41,13 @@ sig_handler(int signo)
 
 int main ()
 {
+    signal(SIGINT, sig_handler);
+
+//! [Interesting]
     maa::Spi* spi;
 
     spi = new maa::Spi(0);
 
-    signal(SIGINT, sig_handler);
-
     uint8_t data[] = {0x00, 100};
     uint8_t *recv;
     while (running == 0) {
@@ -68,6 +69,7 @@ int main ()
 
     }
     delete spi;
+//! [Interesting]
 
     return MAA_SUCCESS;
 }