docs: add common i2c doc page i2c.txt

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

api/mraa/i2c.h

@@ -28,11 +28,9 @@
  * @file
  * @brief Inter-Integrated Circuit
  *
- * This file defines the i2c/Iic interface for libmraa. 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.
+ * An i2c context represents a master on an i2c bus and that context can
+ * communicate to multiple i2c slaves by configuring the address.
+ * @htmlinclude i2c.txt
  *
  * @snippet i2c_HMC5883L.c Interesting
  */

api/mraa/i2c.hpp

@@ -31,7 +31,9 @@ namespace mraa {
 /**
  * @brief API to Inter-Integrated Circuit
  *
- * This file defines the I2c interface for libmraa
+ * An I2c object represents an i2c master and can talk multiple i2c slaves by
+ * selecting the correct address
+ * @htmlinclude i2c.txt
  *
  * @snippet I2c-compass.cpp Interesting
  */

api/mraa/spi.h

@@ -28,7 +28,11 @@
  * @file
  * @brief System Packet Interface
  *
- * This file defines the spi interface for libmraa
+ * This file defines the spi interface for libmraa. A Spi object in libmraa
+ * represents a spidev device. Linux spidev devices are created per spi bus and
+ * every chip select available on that bus has another spidev 'file'. A lot
+ * more information on spidev devices is available
+ * [here](https://www.kernel.org/doc/Documentation/spi/spidev).
  *
  * @snippet spi_mcp4261.c Interesting
  */

docs/i2c.txt

@@ -0,0 +1,3 @@
+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.

src/python/docs/example.rst

@@ -39,6 +39,8 @@ helper function.
   :prepend: x = mraa.I2c(0)
   :start-after: x = mraa.I2c(0)
 
+.. literalinclude:: ../../../docs/i2c.txt
+
 Pwm
 ===