Merge pull request #8 from adafruit/fix-docs

document everything

examples/02texttest/02texttest.ino

@@ -4,12 +4,12 @@
 
 // If your board definition has PIN_CKP and related defines,
 // DVHSTX_PINOUT_DEFAULT is available
-DVHSTXText3 display(DVHSTX_PINOUT_DEFAULT);
+DVHSTXText display(DVHSTX_PINOUT_DEFAULT);
 // If you get the message "error: 'DVHSTX_PINOUT_DEFAULTx' was not declared"
 // then you need to give the pins numbers explicitly, like the example below.
 // The order is: {CKP, D0P, D1P, D2P}.
 //
-// DVHSTXText3 display({12, 14, 16, 18});
+// DVHSTXText display({12, 14, 16, 18});
 
 const static TextColor colors[] = {
     TextColor::TEXT_BLACK, TextColor::TEXT_RED,    TextColor::TEXT_GREEN,

src/Adafruit_dvhstx.cpp

@@ -78,12 +78,12 @@ void DVHSTX8::swap(bool copy_framebuffer) {
   }
 }
 
-void DVHSTXText3::clear() {
+void DVHSTXText::clear() {
   std::fill(getBuffer(), getBuffer() + WIDTH * HEIGHT, attr << 8);
 }
 
 // Character framebuffer is actually a small GFXcanvas16, so...
-size_t DVHSTXText3::write(uint8_t c) {
+size_t DVHSTXText::write(uint8_t c) {
   if (!*this)
     return 0;
 

src/Adafruit_dvhstx.h

@@ -4,31 +4,71 @@
 
 #include "drivers/dvhstx/dvhstx.hpp"
 
-enum DVHSTXResolution {
+#if DOXYGEN
-  /* well supported, square pixels on a 16:9 display, actual resolution
+/// Enumerated types in the library. Due to a technical limitations in the
-     1280x720@50Hz */
+/// documentation generator, these are displayed as members of a class called
-  DVHSTX_RESOLUTION_320x180,
+/// "enum", but in reality they are defined as top-level enumerations.
-  DVHSTX_RESOLUTION_640x360,
+struct enum {
+  public :
+#endif
 
-  /* sometimes supported, square pixels on a 16:9 display, actual resolution
+      /// Available video resolutions
-     960x540@60Hz */
+      enum DVHSTXResolution {
-  DVHSTX_RESOLUTION_480x270,
+        DVHSTX_RESOLUTION_320x180, ///< well supported, aspect ratio 16:9,
+                                   ///< actual resolution 1280x720@50Hz
+        DVHSTX_RESOLUTION_640x360, ///< well supported, aspect ratio 16:9,
+                                   ///< actual resolution 1280x720@50Hz
 
-  /* sometimes supported, square pixels on a 16:9 display, actual resolution
+        DVHSTX_RESOLUTION_480x270, ///< sometimes supported, aspect ratio 16:9,
-     800x450@60Hz */
+                                   ///< actual resolution 960x540@60Hz
-  DVHSTX_RESOLUTION_400x225,
 
-  /* well supported, but pixels aren't square on a 16:9 display */
+        DVHSTX_RESOLUTION_400x225, ///< sometimes supported, aspect ratio 16:9,
-  DVHSTX_RESOLUTION_320x240, /* 4:3, actual resolution 640x480@60Hz */
+                                   ///< actual resolution 800x450@60Hz
-  DVHSTX_RESOLUTION_360x240, /* 3:2, actual resolution 720x480@60Hz */
-  DVHSTX_RESOLUTION_360x200, /* 18:10, actual resolution 720x400@70Hz */
-  DVHSTX_RESOLUTION_360x288, /* 5:4, actual resolution 720x576@60Hz */
-  DVHSTX_RESOLUTION_400x300, /* 4:3, actual resolution 800x600@60Hz */
-  DVHSTX_RESOLUTION_512x384, /* 4:3, actual resolution 1024x768@60Hz */
 
-  /* sometimes supported, but pixels aren't square on a 16:9 display */
+        DVHSTX_RESOLUTION_320x240, ///< well supported, aspect ratio 4:3, actual
-  DVHSTX_RESOLUTION_400x240, /* 5:3, actual resolution 800x480@60Hz */
+                                   ///< resolution 640x480@60Hz
+        DVHSTX_RESOLUTION_360x240, ///< well supported, aspect ratio 3:2, actual
+                                   ///< resolution 720x480@60Hz
+        DVHSTX_RESOLUTION_360x200, ///< well supported, aspect ratio 9:5, actual
+                                   ///< resolution 720x400@70Hz
+        DVHSTX_RESOLUTION_360x288, ///< well supported, aspect ratio 5:4, actual
+                                   ///< resolution 720x576@60Hz
+        DVHSTX_RESOLUTION_400x300, ///< well supported, aspect ratio 4:3, actual
+                                   ///< resolution 800x600@60Hz
+        DVHSTX_RESOLUTION_512x384, ///< well supported, aspect ratio 4:3, actual
+                                   ///< resolution 1024x768@60Hz
+
+        /* sometimes supported, but pixels aren't square on a 16:9 display */
+        DVHSTX_RESOLUTION_400x240, ///< well supported, aspect ratio 5:3, actual
+                                   ///< resolution 800x480@60Hz
+      };
+
+#if DOXYGEN
+  /// Foreground, background & attribute definitions for DVHSTXText Cells
+  enum TextColor{
+      TEXT_BLACK,   ///< Black foreground color
+      TEXT_RED,     ///< Red foreground color
+      TEXT_GREEN,   ///< Green foreground color
+      TEXT_YELLOW,  ///< Yellow foreground color
+      TEXT_BLUE,    ///< Blue foreground color
+      TEXT_MAGENTA, ///< Magenta foreground color
+      TEXT_WHITE,   ///< White foreground color
+
+      BG_BLACK,   ///< Black background color
+      BG_RED,     ///< Red background color
+      BG_GREEN,   ///< Green background color
+      BG_YELLOW,  ///< Yellow background color
+      BG_BLUE,    ///< Blue background color
+      BG_MAGENTA, ///< Magenta background color
+      BG_CYAN,    ///< Cyan background color
+      BG_WHITE,   ///< White background color
+
+      ATTR_NORMAL_INTEN, ///< Normal intensity foreground
+      ATTR_LOW_INTEN,    ///< Lower intensity foreground
+      ATTR_V_LOW_INTEN,  ///< Lowest intensity foreground
+  };
 };
+#endif
 
 using pimoroni::DVHSTXPinout;
 
@@ -54,11 +94,13 @@ using pimoroni::DVHSTXPinout;
 int16_t dvhstx_width(DVHSTXResolution r);
 int16_t dvhstx_height(DVHSTXResolution r);
 
+/// A 16-bit canvas displaying to a DVI monitor
 class DVHSTX16 : public GFXcanvas16 {
 public:
   /**************************************************************************/
   /*!
      @brief    Instatiate a DVHSTX 16-bit canvas context for graphics
+     @param    pinout Details of the HSTX pinout
      @param    res   Display resolution
      @param    double_buffered Whether to allocate two buffers
   */
@@ -69,6 +111,12 @@ public:
         pinout(pinout), res{res}, double_buffered{double_buffered} {}
   ~DVHSTX16() { end(); }
 
+  /**************************************************************************/
+  /*!
+     @brief    Start the display
+     @return   true if successful, false in case of error
+  */
+  /**************************************************************************/
   bool begin() {
     bool result =
         hstx.init(dvhstx_width(res), dvhstx_height(res),
@@ -79,6 +127,11 @@ public:
     fillScreen(0);
     return true;
   }
+  /**************************************************************************/
+  /*!
+     @brief    Stop the display
+  */
+  /**************************************************************************/
   void end() { hstx.reset(); }
 
   /**********************************************************************/
@@ -100,8 +153,8 @@ public:
     @return  The corresponding 16-bit pixel value
   */
   /**********************************************************************/
-  uint16_t color565(uint8_t red, uint8_t green, uint8_t blue) {
+  uint16_t color565(uint8_t r, uint8_t g, uint8_t b) {
-    return ((red & 0xF8) << 8) | ((green & 0xFC) << 3) | (blue >> 3);
+    return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3);
   }
 
 private:
@@ -111,11 +164,13 @@ private:
   bool double_buffered;
 };
 
+/// An 8-bit canvas displaying to a DVI monitor
 class DVHSTX8 : public GFXcanvas8 {
 public:
   /**************************************************************************/
   /*!
      @brief    Instatiate a DVHSTX 8-bit canvas context for graphics
+     @param    pinout Details of the HSTX pinout
      @param    res   Display resolution
      @param    double_buffered Whether to allocate two buffers
   */
@@ -126,6 +181,12 @@ public:
         pinout(pinout), res{res}, double_buffered{double_buffered} {}
   ~DVHSTX8() { end(); }
 
+  /**************************************************************************/
+  /*!
+     @brief    Start the display
+     @return   true if successful, false in case of error
+  */
+  /**************************************************************************/
   bool begin() {
     bool result =
         hstx.init(dvhstx_width(res), dvhstx_height(res),
@@ -142,11 +203,32 @@ public:
     fillScreen(0);
     return true;
   }
+  /**************************************************************************/
+  /*!
+     @brief    Stop the display
+  */
+  /**************************************************************************/
   void end() { hstx.reset(); }
 
-  void setColor(uint8_t idx, uint8_t red, uint8_t green, uint8_t blue) {
+  /**************************************************************************/
-    hstx.get_palette()[idx] = (red << 16) | (green << 8) | blue;
+  /*!
+     @brief    Set the given palette entry to a RGB888 color
+     @param idx The palette entry number, from 0 to 255
+     @param r The input red value, 0 to 255
+     @param g The input red value, 0 to 255
+     @param b The input red value, 0 to 255
+  */
+  /**************************************************************************/
+  void setColor(uint8_t idx, uint8_t r, uint8_t g, uint8_t b) {
+    hstx.get_palette()[idx] = (r << 16) | (g << 8) | b;
   }
+  /**************************************************************************/
+  /*!
+     @brief    Set the given palette entry to a RGB888 color
+     @param idx The palette entry number, from 0 to 255
+     @param rgb The 24-bit RGB value in the form 0x00RRGGBB
+  */
+  /**************************************************************************/
   void setColor(uint8_t idx, uint32_t rgb) { hstx.get_palette()[idx] = rgb; }
 
   /**********************************************************************/
@@ -168,26 +250,54 @@ private:
 
 using TextColor = pimoroni::DVHSTX::TextColour;
 
-class DVHSTXText3 : public GFXcanvas16 {
+/// A text-mode canvas displaying to a DVI monitor
+///
+/// The text mode display is always 91x30 characters at a resolution of 1280x720
+/// pixels.
+class DVHSTXText : public GFXcanvas16 {
 public:
+  /// Each element of the canvas is a Cell, which comprises a character and an
+  /// attribute.
   struct Cell {
-    uint16_t value;
+    uint16_t value; ///< A value where the low 8 bits are the character and the
+                    ///< high 8 bits are the attribute
+    /**************************************************************************/
+    /*!
+       @brief    Create a cell object from an ASCII character and an attribute
+       @param    c ASCII character value. Glyphs from 32 to 126 inclusive are
+       available
+       @param    attr Attribute value. Can be the logical OR of a text color, a
+       background color, and an intensity flag
+    */
+    /**************************************************************************/
     Cell(uint8_t c, uint8_t attr = TextColor::TEXT_WHITE)
         : value(c | (attr << 8)) {}
   };
   /**************************************************************************/
   /*!
      @brief    Instatiate a DVHSTX 8-bit canvas context for graphics
-     @param    double_buffered Whether to allocate two buffers
+     @param    pinout Details of the HSTX pinout
   */
   /**************************************************************************/
-  DVHSTXText3(DVHSTXPinout pinout)
+  DVHSTXText(DVHSTXPinout pinout)
       : GFXcanvas16(91, 30, false), pinout(pinout), res{},
         attr{TextColor::TEXT_WHITE} {}
-  ~DVHSTXText3() { end(); }
+  ~DVHSTXText() { end(); }
 
+  /**************************************************************************/
+  /*!
+     @brief    Check if the display is running
+     @return   true if the display is running
+  */
+  /**************************************************************************/
   operator bool() const { return hstx.get_back_buffer<uint16_t>(); }
 
+  /**************************************************************************/
+  /*!
+     @brief    Start the display
+     @return   true if successful, false in case of error
+  */
+  /**************************************************************************/
   bool begin() {
     bool result =
         hstx.init(91, 30, pimoroni::DVHSTX::MODE_TEXT_RGB111, false, pinout);
@@ -196,26 +306,73 @@ public:
     buffer = hstx.get_back_buffer<uint16_t>();
     return true;
   }
+  /**************************************************************************/
+  /*!
+     @brief    Stop the display
+  */
+  /**************************************************************************/
   void end() { hstx.reset(); }
 
+  /**************************************************************************/
+  /*!
+     @brief    Clear the display. All cells are set to character 32 (space) with
+     the current color
+  */
+  /**************************************************************************/
   void clear();
 
+  /**************************************************************************/
+  /*!
+     @brief    Set the color used by write()
+     @param    a Attribute value. Can be the logical OR of a text color, a
+     background color, and an intensity flag
+  */
+  /**************************************************************************/
   void setColor(uint8_t a) { attr = a; }
+  /**************************************************************************/
+  /*!
+     @brief    Set the color used by write()
+     @param    fg A foreground color
+     @param    bg A background color
+     @param    inten An intensity flag
+  */
+  /**************************************************************************/
   void setColor(TextColor fg, TextColor bg,
                 TextColor inten = TextColor::ATTR_NORMAL_INTEN) {
     attr = fg | bg | inten;
   }
 
+  /**************************************************************************/
+  /*!
+     @brief    Hide the block cursor
+  */
+  /**************************************************************************/
   void hideCursor() {
     cursor_visible = false;
     hstx.cursor_off();
   }
 
+  /**************************************************************************/
+  /*!
+     @brief    Show the block cursor
+  */
+  /**************************************************************************/
   void showCursor() {
     cursor_visible = true;
     sync_cursor_with_hstx();
   }
 
+  /**************************************************************************/
+  /*!
+     @brief    Move the position for write(), and the block cursor (if shown)
+     @param x  The screen location horizontally, from 0 to 91 inclusive
+     @param y  The screen location vertically, from 0 to 29 inclusive
+
+     Note that when the cursor's X position is (zero-based) 91 it is shown on
+     (zero-based) column 90 but the next character written will be wrapped and
+     shown at the beginning of the next line.
+  */
+  /**************************************************************************/
   void setCursor(int x, int y) {
     if (x < 0)
       x = 0;
@@ -230,9 +387,39 @@ public:
     sync_cursor_with_hstx();
   }
 
+  /**************************************************************************/
+  /*!
+     @brief    Write a character to the display
+
+     @param c  The character to write
+
+     Because this class is a subclass of Print, you can also use methods like
+     print, println, and printf to write text.
+
+     Text is written with the current attribute, and the screen automatically
+     wraps and scrolls when needed.
+
+     This function fails (returns 0) if the display was not successfully started
+     with begin().
+
+     @return 1 if the character is written, 0 if it was not
+  */
+  /**************************************************************************/
   size_t write(uint8_t c);
 
+  /**************************************************************************/
+  /*!
+     @brief    Get the current cursor X position, from 0 to 91
+     @return   The column position of the cursor
+  */
+  /**************************************************************************/
   int getCursorX() const { return cursor_x; }
+  /**************************************************************************/
+  /*!
+     @brief    Get the current cursor Y position, from 0 to 29
+     @return   The row position of the cursor
+  */
+  /**************************************************************************/
   int getCursorY() const { return cursor_y; }
 
 private: