Diff: GroveColourSensor.h

Revision:

3:a401a082d57e

Parent:

2:50cb56828ab9

Child:

4:f0e8304db2a3

--- a/GroveColourSensor.h	Wed Apr 15 19:13:11 2015 +0000
+++ b/GroveColourSensor.h	Tue Apr 28 16:09:30 2015 +0000
@@ -19,17 +19,30 @@
 
 #include "mbed.h"
 
+/** RGBC sample struct
+ *  Used for storing 16 bit values of red, green, blue, and clear light channels from the sensor.
+ */
 struct RGBC_Sample {
     uint16_t red, green, blue, clear;
 };
 
+/** RGBC union
+ *  This union wraps the RGBC_Sample struct into an iterable data structure.
+ */
 union RGBC {
     RGBC_Sample ch;
     uint16_t data[4];
 };
 
+/** GroveColourSensor class.
+ *  Library for using the Grove Colour sensor.
+ */
 class GroveColourSensor {
 public:
+
+    /** Color enum
+     *  This enum provides a standard way of enumerating the color channels. The order they are listed is the order in which the values are read from the sensor.
+     */
     enum Colour_t {
         GREEN = 0,
         RED,
@@ -38,19 +51,77 @@
         NUM_COLORS
     };        
 
+    /**
+     *   Constructor, doesn't affect the device at all.
+     *
+     * @param i2c A pointer to the initialized I2C instance.
+     */
     GroveColourSensor(I2C *i2c);
+    
+    /**
+     *   Powers up the color sensor.
+     *   Returns true if successful, otherwise returns false.
+     */
     bool powerUp(void);
-    void powerDown(void);
+    
+    /**
+     *   Powers down the color sensor.
+     *   Returns true if successful, otherwise returns false.
+     */
+    bool powerDown(void);
+    
+    /**
+     *   Set the gain of the color sensor.
+     *
+     *   The following are valid gain values:
+     *   
+     *   - 0 - 1X gain
+     *   - 1 - 4X gain
+     *   - 2 - 16X gain
+     *   - 3 - 64X gain
+     *   
+     * @param gain The gain value specified above.
+     */
     void setGain(uint8_t gain);
+    
+    /**
+     *   Read a specific color.
+     *   
+     * @param colour The color to read (RED, GREEN, BLUE, or CLEAR).
+     */
     uint16_t readColour(Colour_t colour);
+    
+    /**
+     *   Non enum version of readColour()
+     *   
+     * @param colour The integer corresponding to the color you wish to read.
+     */
+    uint16_t readColour(unsigned colour);
+    
+    /**
+     *   Configures the color sensor to expect block reads. Call this before calling readBlock().
+     */
     void setBlockRead();
+    
+    /**
+     *   Read the red, green, blue, and clear channels in one transaction. You must call setBlockRead() before calling this function.
+     *   
+     * @param sample A pointer to the RGBC instance you wish to populate.
+     */
     void readBlock(RGBC *sample);
-    uint16_t readColour(unsigned colour);
+    
+
 
 private:
     static const uint8_t SEVEN_BIT_ADDRESS = 0x39;
     I2C *i2c;
     
+    /**
+     *   Helper function to convert two bytes into a uint16_t.
+     *   
+     * @param lowByte Least signficant byte.
+     * @param highByte Most signficant byte.
+     */
     uint16_t bytesTo16bit(char lowByte, char highByte);
 };