From 2687e5a7c4cb557056913767851bc1203f53f77d Mon Sep 17 00:00:00 2001
From: Brendan Le Foll <brendan.le.foll@intel.com>
Date: Sun, 7 Sep 2014 21:20:06 +0100
Subject: [PATCH] docs: add common i2c doc page i2c.txt

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
---
 api/mraa/i2c.h              | 8 +++-----
 api/mraa/i2c.hpp            | 4 +++-
 api/mraa/spi.h              | 6 +++++-
 docs/i2c.txt                | 3 +++
 src/python/docs/example.rst | 2 ++
 5 files changed, 16 insertions(+), 7 deletions(-)
 create mode 100644 docs/i2c.txt

diff --git a/api/mraa/i2c.h b/api/mraa/i2c.h
index 2b0cf2b..5de3319 100644
--- a/api/mraa/i2c.h
+++ b/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
  */
diff --git a/api/mraa/i2c.hpp b/api/mraa/i2c.hpp
index 0f97bf3..dcd3897 100644
--- a/api/mraa/i2c.hpp
+++ b/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
  */
diff --git a/api/mraa/spi.h b/api/mraa/spi.h
index 5d98ec1..afc785d 100644
--- a/api/mraa/spi.h
+++ b/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
  */
diff --git a/docs/i2c.txt b/docs/i2c.txt
new file mode 100644
index 0000000..19f2c61
--- /dev/null
+++ b/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.
diff --git a/src/python/docs/example.rst b/src/python/docs/example.rst
index d9552ba..1b5ce32 100644
--- a/src/python/docs/example.rst
+++ b/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
 ===