Revision 125:7a0b70f56550, committed 2016-08-01

Comitter:

WiredHome

Date:

Mon Aug 01 22:31:42 2016 +0000

Parent:

124:1690a7ae871c

Child:

126:c91bd2e500b9

Commit message:

Minor documentation tweaks

Changed in this revision

--- a/Bitmap.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/Bitmap.h	Mon Aug 01 22:31:42 2016 +0000
@@ -23,28 +23,30 @@
 #pragma push
 #pragma pack(2)
 
+/// Bitmap file header
 typedef struct                    /**** BMP file header structure ****/
     {
-    uint16_t    bfType;           /* Magic number for file */
-    uint32_t    bfSize;           /* Size of file */
-    uint16_t    bfReserved1;      /* Reserved */
-    uint16_t    bfReserved2;      /* ... */
-    uint32_t    bfOffBits;        /* Offset to bitmap data */
+    uint16_t    bfType;           ///< Magic number for file 
+    uint32_t    bfSize;           ///< Size of file 
+    uint16_t    bfReserved1;      ///< reserved placeholder for the structure footprint
+    uint16_t    bfReserved2;      ///< reserved placeholder for the structure footprint
+    uint32_t    bfOffBits;        ///< Offset to bitmap data 
     } BITMAPFILEHEADER;
 
+/// Bitmap information header
 typedef struct                    /**** BMP file info structure ****/
     {
-    uint32_t    biSize;           /* Size of info header */
-    uint32_t    biWidth;          /* Width of image */
-    uint32_t    biHeight;         /* Height of image */
-    uint16_t    biPlanes;         /* Number of color planes */
-    uint16_t    biBitCount;       /* Number of bits per pixel */
-    uint32_t    biCompression;    /* Type of compression to use */
-    uint32_t    biSizeImage;      /* Size of image data */
-    int32_t     biXPelsPerMeter;  /* X pixels per meter */
-    int32_t     biYPelsPerMeter;  /* Y pixels per meter */
-    uint32_t    biClrUsed;        /* Number of colors used */
-    uint32_t    biClrImportant;   /* Number of important colors */
+    uint32_t    biSize;           ///< Size of info header 
+    uint32_t    biWidth;          ///< Width of image 
+    uint32_t    biHeight;         ///< Height of image 
+    uint16_t    biPlanes;         ///< Number of color planes 
+    uint16_t    biBitCount;       ///< Number of bits per pixel 
+    uint32_t    biCompression;    ///< Type of compression to use 
+    uint32_t    biSizeImage;      ///< Size of image data 
+    int32_t     biXPelsPerMeter;  ///< X pixels per meter 
+    int32_t     biYPelsPerMeter;  ///< Y pixels per meter 
+    uint32_t    biClrUsed;        ///< Number of colors used 
+    uint32_t    biClrImportant;   ///< Number of important colors 
     } BITMAPINFOHEADER;
 #pragma pop
 
@@ -59,12 +61,13 @@
 #  define BI_RLE4      2             /* 4-bit run-length compression */
 #  define BI_BITFIELDS 3             /* RGB bitmap with RGB masks */
 
+/// An RGB Quad data type used by the bitmap driver.
 typedef struct                       /**** Colormap entry structure ****/
     {
-    uint8_t  rgbBlue;          /* Blue value */
-    uint8_t  rgbGreen;         /* Green value */
-    uint8_t  rgbRed;           /* Red value */
-    uint8_t  rgbReserved;      /* Reserved */
+    uint8_t  rgbBlue;          ///< Blue value 
+    uint8_t  rgbGreen;         ///< Green value 
+    uint8_t  rgbRed;           ///< Red value 
+    uint8_t  rgbReserved;      ///< Reserved 
     } RGBQUAD;
 
 //typedef struct                       /**** Bitmap information structure ****/
@@ -77,23 +80,25 @@
 #pragma push
 #pragma pack(2)
 
+/// Icon file type file header.
 typedef struct                  /**** ICO file header structure ****/
     {
-    uint16_t    Reserved_zero;  // Always zero
-    uint16_t    icType;         // 1 for .ico, 2 for .cur
-    uint16_t    icImageCount;   // number of images in the file    
+    uint16_t    Reserved_zero;  ///< Always zero
+    uint16_t    icType;         ///< 1 for .ico, 2 for .cur
+    uint16_t    icImageCount;   ///< number of images in the file    
     } ICOFILEHEADER;
-    
+
+/// Icon file type directory entry structure
 typedef struct                  /**** ICO file Directory Entry structure (1 or more) ****/
     {
-    uint8_t     biWidth;          /* Width of image */
-    uint8_t     biHeight;         /* Height of image */
-    uint8_t     biClrUsed;        /* Number of colors used */
-    uint8_t     Reserved_zero;
-    uint16_t    biPlanes;         /* Number of color planes (ICO should be 0 or 1, CUR horz hotspot */
-    uint16_t    biBitCount;       /* Number of bits per pixel (ICO bits per pixel, CUR vert hotspot */
-    uint32_t    biSizeImage;      /* Size of image data */
-    uint32_t    bfOffBits;        /* Offset into file for the bitmap data */
+    uint8_t     biWidth;        ///< Width of image 
+    uint8_t     biHeight;       ///< Height of image 
+    uint8_t     biClrUsed;      ///< Number of colors used 
+    uint8_t     Reserved_zero;  ///< reserved placeholder for the structure footprint
+    uint16_t    biPlanes;       ///< Number of color planes (ICO should be 0 or 1, CUR horz hotspot 
+    uint16_t    biBitCount;     ///< Number of bits per pixel (ICO bits per pixel, CUR vert hotspot 
+    uint32_t    biSizeImage;    ///< Size of image data 
+    uint32_t    bfOffBits;      ///< Offset into file for the bitmap data 
     } ICODIRENTRY;
 #pragma pop
 

--- a/DisplayDefs.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/DisplayDefs.h	Mon Aug 01 22:31:42 2016 +0000
@@ -4,7 +4,7 @@
 #define RGB(r,g,b) ( ((r<<8)&0xF800) | ((g<<3)&0x07E0) | (b>>3) )
 
 
-/// return values from functions. Use this number, or use the 
+/// Return values from functions. Use this number, or use the 
 /// lookup function to get a text string. @see GetErrorMessage.
 ///
 typedef enum
@@ -33,11 +33,11 @@
     no_cal,                 ///< no calibration matrix is available
 } TouchCode_t;
 
-/// type that manages locations, which is typically an x or y pixel location,
+/// Data type that manages locations, which is typically an x or y pixel location,
 /// which can range from -N to +N (even if the screen is 0 to +n). @see textloc_t.
 typedef int16_t loc_t;
 
-/// type that manages text locations, which are row or column values in
+/// Data type that manages text locations, which are row or column values in
 /// units of character, not pixel. @see loc_t.
 typedef uint16_t textloc_t;
 
@@ -51,7 +51,7 @@
     loc_t y;             ///< y value in the point
 } point_t;
 
-/// type that manages rectangles, which are pairs of points. It is recommended
+/// Data type that manages rectangles, which are pairs of points. It is recommended
 /// that p1 contains the top-left point and p2 contains the bottom-right point,
 /// even though eventually this should not matter.
 typedef struct
@@ -60,9 +60,19 @@
     point_t p2;         ///< p2 defines the opposite point on the rectangle
 } rect_t;
 
+/// Data type that manages the calibration matrix for the resistive touch panel.
+///
+/// This object, when instantiated, may be passed back and forth, stored
+/// and loaded, but the internals are generally of little interest.
 typedef struct
 {
-    int32_t An, Bn, Cn, Dn, En, Fn, Divider;
+    int32_t An;         ///< calibration factor, see source for details
+    int32_t Bn;         ///< calibration factor, see source for details
+    int32_t Cn;         ///< calibration factor, see source for details
+    int32_t Dn;         ///< calibration factor, see source for details
+    int32_t En;         ///< calibration factor, see source for details
+    int32_t Fn;         ///< calibration factor, see source for details
+    int32_t Divider;    ///< calibration factor, see source for details
 } tpMatrix_t;
 
 /// color type definition to let the compiler help keep us honest.

--- a/GraphicsDisplay.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/GraphicsDisplay.h	Mon Aug 01 22:31:42 2016 +0000
@@ -62,7 +62,7 @@
     ///
     /// @param[in] x is the horizontal offset to this pixel.
     /// @param[in] y is the vertical offset to this pixel.
-    /// @returns the pixel. see @color_t
+    /// @returns the pixel. @see color_t
     ///
     virtual color_t getPixel(loc_t x, loc_t y) = 0;
 
@@ -132,8 +132,23 @@
     virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         color_t color, fill_t fillit = FILL) = 0;
 
-
+    /// a function to write the command and data to the RA8875 chip.
+    ///
+    /// @param command is the RA8875 instruction to perform
+    /// @param data is the optional data to the instruction.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF) = 0;
+    
+    
+    /// a function to write the data to the RA8875 chip.
+    ///
+    /// This is typically used after a command has been initiated, and where
+    /// there may be a data stream to follow.
+    ///
+    /// @param data is the optional data to the instruction.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
     virtual RetCode_t WriteData(unsigned char data) = 0;
 
     /// Set the window, which controls where items are written to the screen.
@@ -195,17 +210,30 @@
 
     /// method to fill a region.
     ///
-    /// This method fills a region with the specified color.
+    /// This method fills a region with the specified color. It essentially
+    /// is an alias for fillrect, however this uses width and height rather
+    /// than a second x,y pair.
     ///
     /// @param[in] x is the left-edge of the region.
     /// @param[in] y is the top-edge of the region.
     /// @param[in] w specifies the width of the region.
     /// @param[in] h specifies the height of the region.
+    /// @param[in] color is the color value to use to fill the region
     /// @returns success/failure code. @see RetCode_t.
     /// 
     virtual RetCode_t fill(loc_t x, loc_t y, dim_t w, dim_t h, color_t color);
     
-    
+    /// method to stream bitmap data to the display
+    ///
+    /// This method fills a region from a stream of color data.
+    ///
+    /// @param[in] x is the left-edge of the region.
+    /// @param[in] y is the top-edge of the region.
+    /// @param[in] w specifies the width of the region.
+    /// @param[in] h specifies the height of the region.
+    /// @param[in] color is a pointer to a color stream with w x h values.
+    /// @returns success/failure code. @see RetCode_t.
+    /// 
     virtual RetCode_t blit(loc_t x, loc_t y, dim_t w, dim_t h, const int * color);    
     
     /// This method returns the width in pixels of the chosen character
@@ -423,8 +451,6 @@
     ///
     /// @param[in] x is the horizontal pixel coordinate
     /// @param[in] y is the vertical pixel coordinate
-    /// @param[in] w is the image width restriction, or zero to permit full image width.
-    /// @param[in] h is the image height restriction, or zero to permit full image height.
     /// @param[in] fileOffset is the offset into the file where the image data starts
     /// @param[in] Image is the filename stream already opened for the data.
     /// @returns success or error code.
@@ -507,8 +533,8 @@
     const unsigned char * font;     ///< reference to an external font somewhere in memory
     
     // pixel location
-    short _x;
-    short _y;
+    short _x;                       ///< keeps track of current X location
+    short _y;                       ///< keeps track of current Y location
     
     rect_t windowrect;              ///< window commands are held here for speed of access 
 };

--- a/GraphicsDisplayJPEG.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/GraphicsDisplayJPEG.h	Mon Aug 01 22:31:42 2016 +0000
@@ -22,51 +22,57 @@
 
 #include "DisplayDefs.h"
 
-/* Error code */
+/// Error code results for the jpeg engine
 typedef enum {
-    JDR_OK = noerror, /* 0: Succeeded */
-    JDR_INTR = external_abort,   /* 1: Interrupted by output function */ 
-    JDR_INP = bad_parameter,    /* 2: Device error or wrong termination of input stream */
-    JDR_MEM1 = not_enough_ram,   /* 3: Insufficient memory pool for the image */
-    JDR_MEM2 = not_enough_ram,   /* 4: Insufficient stream input buffer */
-    JDR_PAR = bad_parameter,    /* 5: Parameter error */
-    JDR_FMT1 = not_supported_format,   /* 6: Data format error (may be damaged data) */
-    JDR_FMT2 = not_supported_format,   /* 7: Right format but not supported */
-    JDR_FMT3 = not_supported_format   /* 8: Not supported JPEG standard */
+    JDR_OK = noerror,                   ///< 0: Succeeded 
+    JDR_INTR = external_abort,          ///< 1: Interrupted by output function 
+    JDR_INP = bad_parameter,            ///< 2: Device error or wrong termination of input stream 
+    JDR_MEM1 = not_enough_ram,          ///< 3: Insufficient memory pool for the image 
+    JDR_MEM2 = not_enough_ram,          ///< 4: Insufficient stream input buffer 
+    JDR_PAR = bad_parameter,            ///< 5: Parameter error 
+    JDR_FMT1 = not_supported_format,    ///< 6: Data format error (may be damaged data) 
+    JDR_FMT2 = not_supported_format,    ///< 7: Right format but not supported 
+    JDR_FMT3 = not_supported_format     ///< 8: Not supported JPEG standard 
 } JRESULT;
 
 
 
-/* Rectangular structure */
+/// Rectangular structure definition for the jpeg engine
 typedef struct {
-    loc_t left, right, top, bottom;
+    loc_t left;         ///< left coord
+    loc_t right;        ///< right coord
+    loc_t top;          ///< top coord
+    loc_t bottom;       ///< bottom coord
 } JRECT;
 
 
+/// Decompressor object structure for the jpeg engine
+typedef struct JDEC JDEC;
 
-/* Decompressor object structure */
-typedef struct JDEC JDEC;
+/// Internal structure for the jpeg engine
 struct JDEC {
-    uint16_t dctr;              /* Number of bytes available in the input buffer */
-    uint8_t * dptr;             /* Current data read ptr */
-    uint8_t * inbuf;            /* Bit stream input buffer */
-    uint8_t dmsk;              /* Current bit in the current read byte */
-    uint8_t scale;             /* Output scaling ratio */
-    uint8_t msx, msy;          /* MCU size in unit of block (width, height) */
-    uint8_t qtid[3];           /* Quantization table ID of each component */
-    int16_t dcv[3];           /* Previous DC element of each component */
-    uint16_t nrst;              /* Restart inverval */
-    uint16_t width, height;     /* Size of the input image (pixel) */
-    uint8_t * huffbits[2][2];   /* Huffman bit distribution tables [id][dcac] */
-    uint16_t * huffcode[2][2];   /* Huffman code word tables [id][dcac] */
-    uint8_t * huffdata[2][2];   /* Huffman decoded data tables [id][dcac] */
-    int32_t * qttbl[4];         /* Dequaitizer tables [id] */
-    void * workbuf;          /* Working buffer for IDCT and RGB output */
-    uint8_t * mcubuf;           /* Working buffer for the MCU */
-    void * pool;             /* Pointer to available memory pool */
-    uint16_t sz_pool;           /* Size of momory pool (bytes available) */
-    uint16_t (*infunc)(JDEC * jd, uint8_t * buffer, uint16_t bufsize);/* Pointer to jpeg stream input function */
-    void * device;           /* Pointer to I/O device identifiler for the session */
+    uint16_t dctr;              ///< Number of bytes available in the input buffer 
+    uint8_t * dptr;             ///< Current data read ptr 
+    uint8_t * inbuf;            ///< Bit stream input buffer 
+    uint8_t dmsk;               ///< Current bit in the current read byte 
+    uint8_t scale;              ///< Output scaling ratio 
+    uint8_t msx;                ///< MCU size in unit of block (width, ...) 
+    uint8_t msy;                ///< MCU size in unit of block (..., height) 
+    uint8_t qtid[3];            ///< Quantization table ID of each component 
+    int16_t dcv[3];             ///< Previous DC element of each component 
+    uint16_t nrst;              ///< Restart inverval 
+    uint16_t width;             ///< Size of the input image (pixel width, ...) 
+    uint16_t height;            ///< Size of the input image (..., pixel height) 
+    uint8_t * huffbits[2][2];   ///< Huffman bit distribution tables [id][dcac] 
+    uint16_t * huffcode[2][2];  ///< Huffman code word tables [id][dcac] 
+    uint8_t * huffdata[2][2];   ///< Huffman decoded data tables [id][dcac] 
+    int32_t * qttbl[4];         ///< Dequaitizer tables [id] 
+    void * workbuf;             ///< Working buffer for IDCT and RGB output 
+    uint8_t * mcubuf;           ///< Working buffer for the MCU 
+    void * pool;                ///< Pointer to available memory pool 
+    uint16_t sz_pool;           ///< Size of momory pool (bytes available) 
+    uint16_t (*infunc)(JDEC * jd, uint8_t * buffer, uint16_t bufsize);  ///< Pointer to jpeg stream input function 
+    void * device;              ///< Pointer to I/O device identifiler for the session 
 };
 
 

--- a/RA8875.cpp	Sun Jul 31 20:59:01 2016 +0000
+++ b/RA8875.cpp	Mon Aug 01 22:31:42 2016 +0000
@@ -89,6 +89,8 @@
     "not supported format",   ///< file format is not yet supported
     "image too big",          ///< image is too large for the screen
     "not enough ram",         ///< could not allocate ram for scanline
+    "touch cal. timeout",     ///< calibration could not complete in time
+    "external abort",         ///< during an idle callback, the user code initiated an abort
 };
 
 RA8875::RA8875(PinName mosi, PinName miso, PinName sclk, PinName csel, PinName reset, 

--- a/RA8875.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/RA8875.h	Mon Aug 01 22:31:42 2016 +0000
@@ -13,8 +13,9 @@
 /// of the parallel port options.
 ///
 /// The controller additionally supports backlight control (via PWM), keypad scanning
-/// (for a 4 x 5 matrix) and resistive touch-panel support. Others have provides
-/// support for a capacitive touch screen.
+/// (for a 4 x 5 matrix) and resistive touch-panel support. Recently support for a 
+/// capacitive touch screen was integrated, in a manner that makes the resistive and
+/// capactive interfaces nearly identical.
 ///
 /// @section Display_Config Display Configuration
 ///
@@ -219,7 +220,7 @@
 /// the top-left corner of the display, and the width (x) extends positive to the
 /// right and the height (y) extends positive toward the bottom.
 ///
-/// @caution As there are both graphics and text commands, one must take care to use
+/// @note As there are both graphics and text commands, one must take care to use
 /// the proper coordinate system for each. Some of the text APIs are in units
 /// of column and row, which is measured in character positions (and dependent
 /// on the font size), where other text APIs permit pixel level positioning.
@@ -368,6 +369,7 @@
     ///
     typedef RetCode_t (* PrintCallback_T)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
     
+    /// Idle reason provided in the Idle Callback
     typedef enum {
         unknown,            ///< reason has not been assigned (this should not happen)
         status_wait,        ///< driver is polling the status register while busy
@@ -380,24 +382,44 @@
     /// Idle Callback 
     ///
     /// This defines the interface for an idle callback. That is, when the 
-    /// driver is held up, pending some event, it can call a registered
+    /// driver is held up, pending some event, it can call a previously registered
     /// idle function. This could be most useful for servicing a watchdog.
     ///
     /// The user code, which is notified via this API, can force the idle
     /// to abort, by returning the external_abort value back to the driver.
-    ///
-    /// @param info informs the callback why it is idle.
+    /// It is important to note that the abort could leave the driver in
+    /// an undesireable state, so this should be used with care.
+    ///
+    /// @note Should it be called the BusyCallback? It is true, that it will
+    ///     call this function when the RA8875 is busy, but this is also
+    ///     when the CPU is largely idle.
+    ///
+    /// @code
+    /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason)
+    /// {
+    ///     idleFlasher = !idleFlasher;
+    ///     if (it_has_been_too_long())
+    ///         return external_abort;
+    ///     else
+    ///         return noerror;
+    /// }
+    /// @endcode
+    ///
+    /// @param reason informs the callback why it is idle.
     /// @returns noerror to allow the driver continue waiting.
     /// @returns external_abort if the pending action should be aborted.
     ///
-    typedef RetCode_t (* IdleCallback_T)(IdleReason_T info);
+    typedef RetCode_t (* IdleCallback_T)(IdleReason_T reason);
 
-    /// Constructor for a display based on the RAiO RA8875 
-    /// display controller (use for TouchScreen: Resistive or none)
+    /// Basic constructor for a display based on the RAiO RA8875 
+    /// display controller, which can be used with no touchscreen,
+    /// or the RA8875 managed resistive touchscreen.
     ///
     /// This constructor differs from the alternate by supportting
     /// either No Touch Screen, or the RA8875 built-in resistive
-    /// touch screen.
+    /// touch screen. If the application requires the use of the
+    /// capacitive touchscreen, the alternate constructor should 
+    /// be used.
     ///
     /// This configures the registers and calls the @ref init method.
     ///
@@ -434,6 +456,21 @@
     /// This constructor differs from the alternate by including support
     /// for the Capactive Touch screen.
     ///
+    /// @code
+    /// #include "RA8875.h"
+    /// RA8875 lcd(p5, p6, p7, p12, NC, p9,p10,p13, "tft");
+    /// 
+    /// int main()
+    /// {
+    ///     lcd.init();
+    ///     lcd.printf("printing 3 x 2 = %d", 3*2);
+    ///     lcd.circle(400,25, 25, BrightRed);
+    ///     TouchCode_t tp = lcd.TouchPanelReadable();
+    ///     if (tp == touch)
+    ///         ...
+    /// }
+    /// @endcode
+    ///
     /// @param[in] mosi is the SPI master out slave in pin on the mbed.
     /// @param[in] miso is the SPI master in slave out pin on the mbed.
     /// @param[in] sclk is the SPI shift clock pin on the mbed.
@@ -470,7 +507,7 @@
     /// @param[in] color_bpp can be either 8 or 16, but must be consistent
     ///             with the width and height parameters. This parameter is optional
     ///             and the default is 16.
-    /// @param[in] power defines if the display should be left in the power-on or off state.
+    /// @param[in] poweron defines if the display should be left in the power-on or off state.
     ///            If power is true (on), the backlight is set to 100%. This parameter is optional
     ///             and the default is true (on). See @ref Power.
     /// @param[in] keypadon defines if the keypad support should be enabled. This parameter is optional
@@ -486,6 +523,7 @@
     RetCode_t init(int width = 480, int height = 272, int color_bpp = 16, 
         bool poweron = true, bool keypadon = true, bool touchscreeenon = true);
 
+
     /// Get a pointer to the error code.
     ///
     /// This method returns a pointer to a text string that matches the
@@ -494,6 +532,7 @@
     /// @param[in] code is the return value from RetCode_t to look up.
     /// @returns a pointer to the text message representing code. If code
     ///     is not a valid value, then it returns the text for bad_parameter;
+    ///
     const char * GetErrorMessage(RetCode_t code);
     
     
@@ -523,6 +562,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t SelectDrawingLayer(uint16_t layer);
+ 
     
     /// Get the currently active drawing layer.
     ///
@@ -544,6 +584,7 @@
     /// @returns the current drawing layer; 0 or 1.
     /// 
     uint16_t GetDrawingLayer(void);
+ 
     
     /// Set the Layer presentation mode.
     ///
@@ -566,6 +607,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t SetLayerMode(LayerMode_T mode);
+ 
     
     /// Get the Layer presentation mode.
     ///
@@ -574,6 +616,7 @@
     /// @returns layer mode.
     ///
     LayerMode_T GetLayerMode(void);
+ 
     
     /// Set the layer transparency for each layer.
     ///
@@ -595,6 +638,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     /// 
     RetCode_t SetLayerTransparency(uint8_t layer1, uint8_t layer2);
+ 
     
     /// Set the background color register used for transparency.
     ///
@@ -617,6 +661,7 @@
     ///
     color_t GetBackgroundTransparencyColor(void);
  
+ 
     /// Initialize theTouch Panel controller with default values 
     ///
     /// This activates the simplified touch panel init, which may work for
@@ -627,6 +672,7 @@
     ///
     RetCode_t TouchPanelInit(void);
         
+ 
     /// Initialize the Touch Panel controller with detailed settings.
     ///
     /// This is the detailed touch panel init, which provides the ability
@@ -703,6 +749,7 @@
     ///
     TouchCode_t TouchPanelReadable(point_t * TouchPoint = NULL);
 
+
     /// Get the reported touch gesture, if any.
     /// 
     /// If it could detect a gesture, it will return a value based on
@@ -727,12 +774,14 @@
     /// @returns count of touch points to communicate; 0 to 5.
     ///
     int TouchCount(void) { return numberOfTouchPoints; }
+
     
     /// Get the count of possible touch channels.
     ///
     /// @returns count of touch channels supported by the hardware.
     ///
     int TouchChannels(void);
+
     
     /// Get the Touch ID value for a specified touch channel.
     ///
@@ -753,6 +802,7 @@
     /// @returns 0 if an invalid channel is queried.
     ///
     uint8_t TouchID(uint8_t channel = 0) { return (channel < 5) ? touchInfo[channel].touchID : touchInfo[0].touchID; }
+
     
     /// Get the Touch Code for a touch channel.
     ///
@@ -766,6 +816,7 @@
     ///
     TouchCode_t TouchCode(uint8_t channel = 0) { return (channel < 5) ? touchInfo[channel].touchCode : touchInfo[0].touchCode; }
 
+
     /// Get the coordinates for a touch channel.
     ///
     /// This returns the (X,Y) coordinates for a touch channel.
@@ -780,6 +831,7 @@
     /// @returns channel 0 information if an invalid channel is queried.
     ///
     point_t TouchCoordinates(uint8_t channel = 0)  { return (channel < 5) ? touchInfo[channel].coordinates : touchInfo[0].coordinates; }
+
     
     /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
     ///
@@ -803,6 +855,7 @@
     ///
     TouchCode_t TouchPanelA2DFiltered(int *x, int *y);
 
+
     /// Poll the TouchPanel and on a touch event return the a to d raw x, y coordinates.
     ///
     /// This method reads the touch controller, which has a 10-bit range for each the
@@ -825,6 +878,7 @@
     ///         - release:  indicates a release, touch coordinates are returned.
     ///
     TouchCode_t TouchPanelA2DRaw(int *x, int *y);
+
     
     /// Wait for a touch panel touch and return it.
     /// 
@@ -917,6 +971,7 @@
     ///
     RetCode_t TouchPanelCalibrate(tpMatrix_t * matrix = NULL);
 
+
     /// Perform the touch panel calibration process.
     ///
     /// This method provides the easy "shortcut" to calibrating the touch panel.
@@ -937,6 +992,7 @@
     ///
     RetCode_t TouchPanelCalibrate(const char * msg, tpMatrix_t * matrix = NULL, int maxwait_s = 15);
 
+
     /// Set the calibration matrix for the touch panel.
     ///
     /// This method is used to set the calibration matrix for the touch panel. After
@@ -961,6 +1017,7 @@
     ///
     RetCode_t TouchPanelSetMatrix(tpMatrix_t * matrix);
    
+
 #if 0
     /// Append interrupt handler for specific RA8875 interrupt source
     ///
@@ -988,13 +1045,14 @@
     void UnAppendISR(uint8_t bISRType);
 #endif
 
+
     /// Initialize the keypad interface on the RA8875 controller.
     ///
     /// Enables the keypad subsystem. It will scan the 4 x 5 matrix
     /// and make available key presses. 
     ///
     /// @note See section 5-13 of RAIO RA8875 data sheet for more details.
-    /// @caution When using the display from buy-display.com, be sure that
+    /// @note When using the display from buy-display.com, be sure that
     ///     the option for the keypad is configured on the hardware.
     ///
     /// All parameters are optional.
@@ -1013,6 +1071,7 @@
         uint8_t longTimeAdjustment = 0,
         bool interruptEnable = false, bool wakeupEnable = false);
 
+
     /// Create Key Code definitions for the key matrix.
     ///
     /// This API provides a table of 22 key-code assignments for the matrix of keys.
@@ -1021,7 +1080,7 @@
     ///
     /// In this way, a keypad could easily emulate a piece of a keyboard, transforming
     /// 0 - 20 into the values 0, '0', '1', '2', '3', '4', '5', '6', '7', '8',
-    /// '9', '+', '-', '*' , '/', '=', '<bs>', '<cr>', and so on...
+    /// '9', '+', '-', '*' , '/', '=', '(bs)', '(cr)', and so on...
     ///
     /// @code
     /// //        Return Value by Row, Column   Example reassignment
@@ -1052,15 +1111,17 @@
     ///
     RetCode_t SetKeyMap(const uint8_t * CodeList = NULL);
 
+
     /// Determine if a key has been hit
     ///
     /// @returns true if a key has been hit
     ///
     bool readable();
 
+
     /// Blocking read of the keypad.
     ///
-    /// @caution: This is a blocking read, so it is important to first call _kbhit()
+    /// @note: This is a blocking read, so it is important to first call _kbhit()
     ///         to avoid hanging your processes.
     ///
     /// A keypad connected to the RA8875 is connected in a matrix of 4 rows and 5 columns.
@@ -1096,6 +1157,7 @@
     ///
     RetCode_t WriteCommandW(uint8_t command, uint16_t data);
 
+
     /// Write a command to the display
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1106,6 +1168,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF);
+
     
     /// Write a data word to the display
     ///
@@ -1115,6 +1178,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t WriteDataW(uint16_t data);
+
     
     /// Write a data byte to the display
     ///
@@ -1124,6 +1188,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t WriteData(unsigned char data);
+
     
     /// Read a command register
     ///
@@ -1132,6 +1197,7 @@
     ///
     unsigned char ReadCommand(unsigned char command);
     
+
     /// Read a data byte from the display
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1139,6 +1205,7 @@
     /// @returns data that was read.
     ///
     unsigned char ReadData(void);
+
     
     /// Read a word from the display
     ///
@@ -1148,6 +1215,7 @@
     ///
     uint16_t ReadDataW(void);
 
+
     /// Read the display status
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1156,17 +1224,20 @@
     ///
     unsigned char ReadStatus(void);
 
+
     /// get the width in pixels of the currently active font
     ///
     /// @returns font width in pixels.
     ///    
     dim_t fontwidth(void);
     
+
     /// get the height in pixels of the currently active font
     ///
     /// @returns font height in pixels.
     ///    
     dim_t fontheight(void);
+
     
     /// get the number of colums based on the currently active font
     ///
@@ -1174,24 +1245,28 @@
     ///    
     virtual int columns(void);
 
+
     /// get the number of rows based on the currently active font
     ///
     /// @returns number of rows.
     ///    
     virtual int rows(void);
 
+
     /// get the screen width in pixels
     ///
     /// @returns screen width in pixels.
     ///
     virtual dim_t width(void);
 
+
     /// get the screen height in pixels
     ///
     /// @returns screen height in pixels.
     ///
     virtual dim_t height(void);
 
+
     /// get the color depth in bits per pixel.
     ///
     /// @returns 8 or 16 only.
@@ -1206,6 +1281,7 @@
     ///
     virtual RetCode_t locate(textloc_t column, textloc_t row);
 
+
     /// Prepare the controller to write text to the screen by positioning
     /// the cursor.
     ///
@@ -1220,6 +1296,7 @@
     ///
     RetCode_t SetTextCursor(loc_t x, loc_t y);
 
+
     /// Prepare the controller to write text to the screen by positioning
     /// the cursor.
     ///
@@ -1234,6 +1311,7 @@
     ///
     RetCode_t SetTextCursor(point_t p);
 
+
     /// Get the current cursor position in pixels.
     ///
     /// @code
@@ -1246,18 +1324,21 @@
     ///
     point_t GetTextCursor(void);
     
+
     /// Get the current cursor horizontal position in pixels.
     ///
     /// @returns cursor position horizontal offset.
     ///
     loc_t GetTextCursor_X(void);
 
+
     /// Get the current cursor vertical position in pixels.
     ///
     /// @returns cursor position vertical offset.
     ///
     loc_t GetTextCursor_Y(void);
 
+
     /// Configure additional Cursor Control settings.
     ///
     /// This API lets you modify other cursor control settings; 
@@ -1270,12 +1351,13 @@
     /// @returns success/failure code. See @ref RetCode_t
     ///
     RetCode_t SetTextCursorControl(cursor_t cursor = NOCURSOR, bool blink = false);
+
     
     /// Select the built-in ISO 8859-X font to use next.
     ///
     /// Supported fonts: ISO 8859-1, -2, -3, -4
     ///
-    /// @caution This only modifies the choice of font from the RA8875 internal
+    /// @note This only modifies the choice of font from the RA8875 internal
     ///     fonts.
     ///
     /// @param[in] font selects the font for the subsequent text rendering.
@@ -1286,6 +1368,7 @@
     ///
     RetCode_t SetTextFont(font_t font = ISO8859_1);
     
+
     /// Sets the display orientation.
     ///
     /// @note This command does not let you "merge" text onto an existing
@@ -1294,7 +1377,7 @@
     ///       to sending text to the screen, or you end with a blended
     ///       image that is probably not as intended.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// @code
     ///     lcd.cls();
@@ -1327,12 +1410,13 @@
     ///
     RetCode_t SetOrientation(orientation_t angle = normal);
     
+
     /// Control the font behavior.
     ///
     /// This command lets you make several modifications to any text that
     /// will be written to the screen.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// Options can be combined:
     /// Default:
@@ -1364,13 +1448,14 @@
         VerticalScale vScale = 1, 
         alignment_t alignment = align_none);
     
+
     /// Control the font size of the RA8875 internal fonts.
     ///
     /// This command lets you set the font enlargement for both horizontal
     /// and vertical, independent of the rotation, background, and 
     /// alignment. See @ref SetTextFontControl.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// @param[in] hScale defaults to 1, but can be 1, 2, 3, or 4,
     ///     and scales the font size by this amount.
@@ -1392,6 +1477,7 @@
     ///
     RetCode_t SetTextFontSize(HorizontalScale hScale = 1, VerticalScale vScale = -1);
     
+
     /// put a character on the screen.
     ///
     /// @param[in] c is the character.
@@ -1399,6 +1485,7 @@
     ///
     virtual int _putc(int c);
 
+
     /// Write string of text to the display
     ///
     /// @code
@@ -1408,6 +1495,7 @@
     /// @param[in] string is the null terminated string to send to the display.
     ///
     void puts(const char * string);
+
     
     /// Write string of text to the display at the specified location.
     ///
@@ -1421,6 +1509,7 @@
     ///
     void puts(loc_t x, loc_t y, const char * string);
     
+
     /// Prepare the controller to write binary data to the screen by positioning
     /// the memory cursor.
     ///
@@ -1429,6 +1518,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t SetGraphicsCursor(loc_t x, loc_t y);
+
     
     /// Prepare the controller to read binary data from the screen by positioning
     /// the memory read cursor.
@@ -1439,6 +1529,7 @@
     ///
     virtual RetCode_t SetGraphicsCursorRead(loc_t x, loc_t y);
     
+
     /// Set the window, constraining where items are written to the screen.
     ///
     /// After setting the window, text and graphics are constrained to this
@@ -1465,6 +1556,7 @@
     ///
     virtual RetCode_t window(rect_t r);
     
+
     /// Set the window, constraining where items are written to the screen.
     ///
     /// After setting the window, text and graphics are constrained to this
@@ -1495,6 +1587,7 @@
     ///
     virtual RetCode_t window(loc_t x = 0, loc_t y = 0, dim_t width = (dim_t)-1, dim_t height = (dim_t)-1);
     
+
     /// Clear either the specified layer, or the active layer.
     ///
     /// The behavior is to clear the whole screen for the specified
@@ -1514,6 +1607,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t cls(uint16_t layers = 0);
+
     
     /// Clear the screen, or clear only the active window.
     ///
@@ -1532,12 +1626,14 @@
     ///
     RetCode_t clsw(RA8875::Region_t region = FULLWINDOW);
 
+
     /// Set the background color.
     ///
     /// @param[in] color is expressed in 16-bit format.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t background(color_t color);
+
     
     /// Set the background color.
     ///
@@ -1548,6 +1644,7 @@
     ///
     virtual RetCode_t background(unsigned char r, unsigned char g, unsigned char b);
     
+
     /// Set the foreground color.
     ///
     /// @param[in] color is expressed in 16-bit format.
@@ -1555,6 +1652,7 @@
     ///
     virtual RetCode_t foreground(color_t color);
     
+
     /// Set the foreground color.
     ///
     /// @param[in] r is the red element of the color.
@@ -1564,12 +1662,14 @@
     ///
     virtual RetCode_t foreground(unsigned char r, unsigned char g, unsigned char b);
     
+    
     /// Get the current foreground color value.
     ///
     /// @returns the current foreground color.
     ///
     color_t GetForeColor(void);
     
+    
     /// Draw a pixel in the specified color.
     ///
     /// @note Unlike many other operations, this does not
@@ -1580,12 +1680,14 @@
     ///
     virtual RetCode_t pixel(point_t p, color_t color);
     
+    
     /// Draw a pixel in the current foreground color.
     ///
     /// @param[in] p is the point_t defining the location.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t pixel(point_t p);
+    
         
     /// Draw a pixel in the specified color.
     ///
@@ -1599,6 +1701,7 @@
     ///
     virtual RetCode_t pixel(loc_t x, loc_t y, color_t color);
     
+    
     /// Draw a pixel in the current foreground color.
     ///
     /// @param[in] x is the horizontal offset to this pixel.
@@ -1607,6 +1710,7 @@
     ///
     virtual RetCode_t pixel(loc_t x, loc_t y);
     
+    
     /// Get a pixel from the display.
     ///
     /// @param[in] x is the horizontal offset to this pixel.
@@ -1615,6 +1719,7 @@
     ///
     virtual color_t getPixel(loc_t x, loc_t y);
     
+    
     /// Write a stream of pixels to the display.
     ///
     /// @param[in] p is a pointer to a color_t array to write.
@@ -1625,6 +1730,7 @@
     ///
     virtual RetCode_t pixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
     
+    
     /// Get a stream of pixels from the display.
     ///
     /// @param[in] p is a pointer to a color_t array to accept the stream.
@@ -1635,6 +1741,7 @@
     ///
     virtual RetCode_t getPixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
     
+    
     /// Write a boolean stream to the display.
     ///
     /// This takes a bit stream in memory and using the current color settings
@@ -1654,6 +1761,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t booleanStream(loc_t x, loc_t y, dim_t w, dim_t h, const uint8_t * boolStream);
+
     
     /// Draw a line in the specified color
     ///
@@ -1667,6 +1775,7 @@
     ///
     RetCode_t line(point_t p1, point_t p2, color_t color);
 
+
     /// Draw a line
     ///
     /// Draws a line using the foreground color setting.
@@ -1676,6 +1785,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t line(point_t p1, point_t p2);
+
     
     /// Draw a line in the specified color
     ///
@@ -1691,6 +1801,7 @@
     ///
     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2, color_t color);
 
+
     /// Draw a line
     ///
     /// Draws a line using the foreground color setting.
@@ -1703,6 +1814,7 @@
     ///
     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2);
 
+
     /// Draw a rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1715,7 +1827,8 @@
     ///
     RetCode_t rect(rect_t rect, color_t color, fill_t fillit = NOFILL);
     
-     /// Draw a filled rectangle in the specified color
+
+    /// Draw a filled rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
     ///     foreground color for subsequent operations.
@@ -1727,6 +1840,7 @@
     ///
     RetCode_t fillrect(rect_t rect, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1743,6 +1857,7 @@
     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1759,6 +1874,7 @@
     virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle
     ///
     /// Draws a rectangle using the foreground color setting.
@@ -1773,6 +1889,7 @@
     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         fill_t fillit = NOFILL);
 
+
     /// Draw a filled rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1800,6 +1917,7 @@
     RetCode_t fillroundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a filled rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1824,6 +1942,7 @@
     RetCode_t fillroundrect(rect_t r, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1848,6 +1967,7 @@
     RetCode_t roundrect(rect_t r, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1875,6 +1995,7 @@
     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a rectangle with rounded corners.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1898,6 +2019,7 @@
     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
 
+
     /// Draw a triangle in the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1916,6 +2038,7 @@
     RetCode_t triangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         loc_t x3, loc_t y3, color_t color, fill_t fillit = NOFILL);
     
+
     /// Draw a filled triangle in the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1934,6 +2057,7 @@
     RetCode_t filltriangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         loc_t x3, loc_t y3, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a triangle
     ///
     /// Draws a triangle using the foreground color setting.
@@ -1959,10 +2083,12 @@
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(point_t p, dim_t radius, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1971,20 +2097,24 @@
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is FILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t fillcircle(point_t p, dim_t radius, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a circle.
     ///
     /// Draws a circle using the foreground color setting.
     ///
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(point_t p, dim_t radius, fill_t fillit = NOFILL);
 
+
     /// Draw a circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1994,10 +2124,12 @@
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -2007,10 +2139,12 @@
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is FILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t fillcircle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a circle.
     ///
     /// Draws a circle using the foreground color setting.
@@ -2018,6 +2152,7 @@
     /// @param[in] x is the horizontal center of the circle.
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(loc_t x, loc_t y, dim_t radius, fill_t fillit = NOFILL);
@@ -2038,6 +2173,7 @@
     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
         color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled Ellipse using the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -2054,6 +2190,7 @@
     RetCode_t fillellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
         color_t color, fill_t fillit = FILL);
 
+
     /// Draw an Ellipse
     ///
     /// Draws it using the foreground color setting.
@@ -2067,6 +2204,7 @@
     ///
     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
     
+
     /// Control display power
     ///
     /// @param[in] on when set to true will turn on the display, when false it is turned off.
@@ -2074,12 +2212,14 @@
     ///
     RetCode_t Power(bool on);
 
+
     /// Reset the display controller via the Software Reset interface.
     ///
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t Reset(void);
     
+
     /// Set backlight brightness.
     ///
     /// When the built-in PWM is used to control the backlight, this 
@@ -2089,6 +2229,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t Backlight_u8(unsigned char brightness);
+
     
     /// Get backlight brightness.
     ///
@@ -2106,12 +2247,14 @@
     ///
     RetCode_t Backlight(float brightness);
 
+
     /// Get backlight brightness.
     ///
     /// @returns backlight setting from 0 (off) to 1.0 (full on).
     /// 
     float GetBacklight(void);
 
+
     /// Select a User Font for all subsequent text.
     ///
     /// @note Tool to create the fonts is accessible from its creator
@@ -2124,24 +2267,33 @@
     ///
     virtual RetCode_t SelectUserFont(const uint8_t * font = NULL);
 
-    typedef uint8_t byte;
 
     /// Get the RGB value for a DOS color.
     ///
+    /// @code
+    ///     color_t color = DOSColor(12);
+    /// @endcode
+    ///
     /// @param[in] i is the color, in the range 0 to 15;
     /// @returns the RGB color of the selected index, or 0 
     ///     if the index is out of bounds.
     ///
     color_t DOSColor(int i);
 
+
     /// Get the color name (string) for a DOS color.
     ///
+    /// @code
+    ///     printf("color is %s\n", DOSColorNames(12));
+    /// @endcode
+    ///
     /// @param[in] i is the color, in the range 0 to 15;
     /// @returns a pointer to a string with the color name,
     ///     or NULL if the index is out of bounds.
     /// 
     const char * DOSColorNames(int i);
 
+
     /// Advanced method indicating the start of a graphics stream.
     ///
     /// This is called prior to a stream of pixel data being sent.
@@ -2158,6 +2310,7 @@
     /// @returns error code.
     ///
     virtual RetCode_t _StartGraphicsStream(void);
+
     
     /// Advanced method to put a single color pixel to the screen.
     ///
@@ -2165,10 +2318,15 @@
     /// See @ref _StartGraphicsStream() is called, and it should be followed 
     /// by _EndGraphicsStream.
     ///
+    /// @code
+    ///     _putp(DOSColor(12));
+    /// @endcode
+    ///
     /// @param[in] pixel is a color value to be put on the screen.
     /// @returns error code.
     ///
     virtual RetCode_t _putp(color_t pixel);
+
     
     /// Advanced method indicating the end of a graphics stream.
     ///
@@ -2181,6 +2339,7 @@
     ///
     virtual RetCode_t _EndGraphicsStream(void);
 
+
     /// Set the SPI port frequency (in Hz).
     ///
     /// This uses the mbed SPI driver, and is therefore dependent on
@@ -2209,7 +2368,8 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t frequency(unsigned long Hz = RA8875_DEFAULT_SPI_FREQ, unsigned long Hz2 = 0);
-    
+
+
     /// This method captures the specified area as a 24-bit bitmap file.
     ///
     /// Even though this is a 16-bit display, the stored image is in
@@ -2228,6 +2388,7 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
+
     
     /// This method captures the specified area as a 24-bit bitmap file
     /// and delivers it to the previously attached callback.
@@ -2248,6 +2409,7 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h);
+
     
     /// PrintScreen callback registration.
     ///
@@ -2260,6 +2422,7 @@
     ///
     void AttachPrintHandler(PrintCallback_T callback = NULL) { c_callback = callback; }
 
+
     /// PrintScreen callback registration.
     ///
     /// This method attaches a c++ class method as a callback of type PrintCallback_T.
@@ -2275,10 +2438,11 @@
         method_callback = (uint32_t (FPointerDummy::*)(uint32_t, uint8_t *, uint16_t))method;
     }
 
+
     /// This method captures the specified area as a 24-bit bitmap file,
     /// including the option of layer selection.
     ///
-    /// @caution This method is deprecated as the alternate PrintScreen API
+    /// @note This method is deprecated as the alternate PrintScreen API
     ///         automatically examines the display layer configuration.
     ///         Therefore, calls to this API will ignore the layer parameter
     ///         and automatically execute the other method.
@@ -2295,10 +2459,11 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(uint16_t layer, loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
+
     
     /// idle callback registration.
     ///
-    /// This method attaches a simple c-compatible callback of type XXXXXXXXXXX.
+    /// This method attaches a simple c-compatible callback of type IdleCallback_T.
     /// Then, at any time when the display driver is waiting, it will call the
     /// registered function. This is probably most useful if you want to service
     /// a watchdog, when you may have called an API that will "hang" waiting

--- a/TextDisplay.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/TextDisplay.h	Mon Aug 01 22:31:42 2016 +0000
@@ -123,18 +123,27 @@
     // putc (from Stream)
     // printf (from Stream)
 
-protected:    
+protected:
+    /// a method to put a character to the display.
+    ///
+    /// @param value is the character value to send to the display
+    /// @returns the character that was sent.
+    ///
     virtual int _putc(int value);
+    
+    /// a method to get a character from the stdin
+    /// 
+    /// @returns the fetched character.
+    ///
     virtual int _getc();
 
-    // character location
-    uint16_t _column;
-    uint16_t _row;
+    uint16_t _column;           ///< character column location
+    uint16_t _row;              ///< character row location
 
     // colors
-    color_t _foreground;
-    color_t _background;
-    char *_path;
+    color_t _foreground;        ///< presently set foreground color
+    color_t _background;        ///< presently set background color
+    char *_path;                ///< stream name when redirecting stdio
 };
 
 #endif