lcd: overhaul documentation for lcd module

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

examples/lcm-lcd.cxx

@@ -27,9 +27,11 @@
 int
 main(int argc, char **argv)
 {
+//! [Interesting]
     upm::Lcm1602* lcd = new upm::Lcm1602(0, 0x27);
     lcd->setCursor(0,0);
     lcd->write("Hello World");
+//! [Interesting]
     lcd->setCursor(1,2);
     lcd->write("Hello World");
     lcd->setCursor(2,4);

examples/oled-1308.cxx

@@ -83,13 +83,16 @@ static uint8_t intel_logo[] = {
     63, 63, 63, 63, 63, 31, 31, 31, 31, 31, 15, 15, 15, 15, 7, 7, 7, 7, 3, 3,
     3, 3, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     0, 0, 0, 0, 0, 0, 0 };
+
 int
 main(int argc, char **argv)
 {
-    upm::SSD1308 *lcd = new upm::SSD1308 (BUS_NUMBER, DEVICE_ADDRESS);
+//! [Interesting]
+    upm::SSD1308 *lcd = new upm::SSD1308(BUS_NUMBER, DEVICE_ADDRESS);
 
-    lcd->clear ();
+    lcd->clear();
-    lcd->draw (intel_logo, 1024);
+    lcd->draw(intel_logo, 1024);
 
-    lcd->close ();
+    lcd->close();
+//! [Interesting]
 }

examples/oled-1327.cxx

@@ -106,21 +106,19 @@ static uint8_t SeeedLogo[] ={
 int
 main(int argc, char **argv)
 {
-    upm::SSD1327 *lcd = new upm::SSD1327 (BUS_NUMBER, 0x3C);
+//! [Interesting]
+    upm::SSD1327 *lcd = new upm::SSD1327(BUS_NUMBER, 0x3C);
 
-    /*
+    // Simple print hello world
-     * Simple print hello world
+    for (uint8_t i = 0; i < 12; i++) {
-     */
+        lcd->setCursor(i, 0);
-    for(uint8_t i = 0; i < 12 ; i++) {
+        lcd->setGrayLevel(i);
-        lcd->setCursor (i, 0);
+        lcd->write("Hello World");
-        lcd->setGrayLevel (i);
-        lcd->write ("Hello World");
     }
 
-   /*
+    // Simple print hello world
-     * Simple print hello world
+    lcd->draw(SeeedLogo, 96 * 96 / 8);
-     */
-    lcd->draw (SeeedLogo, 96 * 96 / 8);
 
-    lcd->close ();
+    lcd->close();
+//! [Interesting]
 }

examples/rgb-lcd.cxx

@@ -27,6 +27,7 @@
 int
 main(int argc, char **argv)
 {
+//! [Interesting]
     // 0x62 RGB_ADDRESS, 0x3E LCD_ADDRESS
     upm::Jhd1313m1 *lcd = new upm::Jhd1313m1(0, 0x3E, 0x62);
     lcd->setCursor(0,0);
@@ -34,4 +35,5 @@ main(int argc, char **argv)
     lcd->setCursor(1,2);
     lcd->write("Hello World");
     lcd->close();
+//! [Interesting]
 }

src/lcd/jhd1313m1.h

@@ -28,16 +28,70 @@
 
 namespace upm {
 
+/**
+ * @brief C++ API for Jhd1313m1 i2c controller for HD44780 based displays with
+ * an RGB backlight such as the Grove RGB i2c LCD display
+ *
+ * @snippet rgb-lcd.cxx Interesting
+ */
 class Jhd1313m1 : public I2CLcd {
     public:
-        Jhd1313m1 (int bus, int lcdAddress, int rgbAddress);
+       /**
-        ~Jhd1313m1 ();
+        * Jhd1313m1 constructor
-        mraa_result_t setColor(uint8_t r, uint8_t g, uint8_t b);
+        *
-        mraa_result_t write (std::string msg);
+        * @param bus i2c bus to use
-        mraa_result_t setCursor (int row, int column);
+        * @param address the slave address the lcd is registered on
-        mraa_result_t clear ();
+        * @param address the slave address the rgb backlight is on
-        mraa_result_t home ();
+        */
+        Jhd1313m1(int bus, int lcdAddress, int rgbAddress);
+       /**
+        * Jhd1313m1 destructor
+        */
+        ~Jhd1313m1();
+       /**
+        * Make the LCD scroll text
+        *
+        * @param direction, true is typical scrolling to the right
+        * @return Result of operation
+        */
         mraa_result_t scroll (bool direction);
+       /**
+        * Set the color of the backlight
+        *
+        * @param r 0-255 value for red
+        * @param g 0-255 value for green
+        * @param b 0-255 value for blue
+        * @return Result of operation
+        */
+        mraa_result_t setColor(uint8_t r, uint8_t g, uint8_t b);
+       /**
+        * Write a string to LCD
+        *
+        * @param msg The std::string to write to display, note only ascii
+        *     chars are supported
+        * @return Result of operation
+        */
+        mraa_result_t write(std::string msg);
+       /**
+        * Set cursor to a coordinate
+        *
+        * @param row The row to set cursor to
+        * @param column The column to set cursor to
+        * @return Result of operation
+        */
+        mraa_result_t setCursor(int row, int column);
+       /**
+        * Clear display from characters
+        *
+        * @return Result of operatio
+        */
+        mraa_result_t clear();
+       /**
+        * Return to coordinate 0,0
+        *
+        * @return Result of operation
+        */
+        mraa_result_t home();
 
     private:
         int m_rgb_address;

src/lcd/lcm1602.h

@@ -32,22 +32,59 @@
 
 namespace upm {
 
+/**
+ * @brief C++ API for LCM1602 i2c controller for HD44780 based displays
+ *
+ * This supports all sizes of HD44780 displays from 16x2 to 4x20, the
+ * controller has no idea of the actual display hardware so will let you write
+ * further than you can see
+ *
+ * @snippet lcm-lcd.cxx Interesting
+ */
 class Lcm1602 : public I2CLcd {
     public:
-        /** LCM1602 Constructor.
+       /**
-         * Calls MRAA initialisation functions.
+        * Lcm1602 Constructor, calls libmraa initialisation functions
-         * @param bus i2c bus to use
+        *
-         * @param address the slave address the lcd is registered on.
+        * @param bus i2c bus to use
-         */
+        * @param address the slave address the lcd is registered on
+        */
         Lcm1602(int bus, int address);
+       /**
+        * Lcm1602 Destructor
+        */
         ~Lcm1602();
-        mraa_result_t write (std::string msg);
+       /**
-        mraa_result_t setCursor (int row, int column);
+        * Write a string to LCD
-        mraa_result_t clear ();
+        *
-        mraa_result_t home ();
+        * @param msg The std::string to write to display, note only ascii
+        *     chars are supported
+        * @return Result of operation
+        */
+        mraa_result_t write(std::string msg);
+       /**
+        * Set cursor to a coordinate
+        *
+        * @param row The row to set cursor to
+        * @param column The column to set cursor to
+        * @return Result of operation
+        */
+        mraa_result_t setCursor(int row, int column);
+       /**
+        * Clear display from characters
+        *
+        * @return Result of operatio
+        */
+        mraa_result_t clear();
+       /**
+        * Return to coordinate 0,0
+        *
+        * @return Result of operation
+        */
+        mraa_result_t home();
 
     private :
-        mraa_result_t send (uint8_t value, int mode);
+        mraa_result_t send(uint8_t value, int mode);
         mraa_result_t write4bits(uint8_t value);
         mraa_result_t expandWrite(uint8_t value);
         mraa_result_t pulseEnable(uint8_t value);

src/lcd/ssd1308.h

@@ -145,23 +145,61 @@ typedef enum {
     PAGE          =  2
 } displayAddressingMode;
 
+/**
+ * @brief C++ API for SSD1308 i2c controlled OLED displays
+ *
+ * @snippet lcm-lcd.cxx Interesting
+ */
 class SSD1308 : public I2CLcd {
     public:
-        /** SSD1308 Constructor.
+       /**
-         * Calls MRAA initialisation functions.
+        * SSD1308 Constructor, calls libmraa initialisation functions
-         * @param bus i2c bus to use
+        *
-         * @param address the slave address the lcd is registered on.
+        * @param bus i2c bus to use
-         */
+        * @param address the slave address the lcd is registered on
+        */
         SSD1308 (int bus, int address);
+       /**
+        * SSD1308 Destructor
+        */
         ~SSD1308 ();
+       /**
+        * Draw an image, see examples/python/make_oled_pic.py for an
+        * explanation on how the pixels are mapped to bytes
+        *
+        * @param data the buffer to read
+        * @param bytes the amount of bytes to read from the pointer
+        * @return Result of operation
+        */
         mraa_result_t draw(uint8_t *data, int bytes);
-
+       /**
-        // pure virtual methods
+        * Write a string to LCD
-        mraa_result_t write (std::string msg);
+        *
-        mraa_result_t setCursor (int row, int column);
+        * @param msg The std::string to write to display, note only ascii
-        mraa_result_t clear ();
+        *     chars are supported
-        mraa_result_t home ();
+        * @return Result of operation
-
+        */
+        mraa_result_t write(std::string msg);
+       /**
+        * Set cursor to a coordinate
+        *
+        * @param row The row to set cursor to
+        * @param column The column to set cursor to
+        * @return Result of operation
+        */
+        mraa_result_t setCursor(int row, int column);
+       /**
+        * Clear display from characters
+        *
+        * @return Result of operatio
+        */
+        mraa_result_t clear();
+       /**
+        * Return to coordinate 0,0
+        *
+        * @return Result of operation
+        */
+        mraa_result_t home();
     private:
         mraa_result_t writeChar (mraa_i2c_context ctx, uint8_t value);
         mraa_result_t setNormalDisplay ();

src/lcd/ssd1327.h

@@ -147,21 +147,61 @@ typedef enum {
 
 class SSD1327 : public I2CLcd {
     public:
-        /** SSD1308 Constructor.
+        /**
-         * Calls MRAA initialisation functions.
+         * SSD1308 Constructor, calls libmraa initialisation functions
+         *
          * @param bus i2c bus to use
-         * @param address the slave address the lcd is registered on.
+         * @param address the slave address the lcd is registered on
          */
         SSD1327 (int bus, int address);
+       /**
+        * SSD1327 destructor
+        */
         ~SSD1327 ();
+       /**
+        * Draw an image, see examples/python/make_oled_pic.py for an
+        * explanation on how the pixels are mapped to bytes
+        *
+        * @param data the buffer to read
+        * @param bytes the amount of bytes to read from the pointer
+        * @return Result of operation
+        */
         mraa_result_t draw(uint8_t *data, int bytes);
-
+       /**
-        // virtual methods
+        * Set gray level for LCD panel
-        mraa_result_t write (std::string msg);
+        *
-        mraa_result_t setCursor (int row, int column);
+        * @param gray level from 0-255
-        mraa_result_t clear ();
+        * @return Result of operation
-        mraa_result_t home ();
+        */
         mraa_result_t setGrayLevel (uint8_t level);
+       /**
+        * Write a string to LCD
+        *
+        * @param msg The std::string to write to display, note only ascii
+        *     chars are supported
+        * @return Result of operation
+        */
+        mraa_result_t write(std::string msg);
+       /**
+        * Set cursor to a coordinate
+        *
+        * @param row The row to set cursor to
+        * @param column The column to set cursor to
+        * @return Result of operation
+        */
+        mraa_result_t setCursor(int row, int column);
+       /**
+        * Clear display from characters
+        *
+        * @return Result of operatio
+        */
+        mraa_result_t clear();
+       /**
+        * Return to coordinate 0,0
+        *
+        * @return Result of operation
+        */
+        mraa_result_t home();
 
     private:
         mraa_result_t writeChar (mraa_i2c_context ctx, uint8_t value);