Diff: RA8875.h

Revision:

21:3c1efb192927

Parent:

20:6e2e4a8372eb

Child:

22:f6ea795eb541

--- a/RA8875.h	Sun Jan 12 18:44:58 2014 +0000
+++ b/RA8875.h	Sun Jan 12 21:11:15 2014 +0000
@@ -63,6 +63,19 @@
 //    bad_parameter
 //} RetCode_t;
 
+/// This is a graphics library for the Raio RA8875 Display Controller chip
+/// attached to a 4-wire SPI interface.
+///
+/// It offers both primitive and high level APIs.
+/// Central to this API is a coordinate system, where the origin (0,0) is in
+/// the top-left corner of the display, and the width extends positive to the
+/// right and the height extends positive toward the bottom.
+///
+/// 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 (so dependent
+/// on the font size).
+/// 
 class RA8875 : public GraphicsDisplay
 {
 public:   
@@ -476,15 +489,24 @@
 
     /// 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,
+    /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
+    /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
+    /// > 1/2 the length of that side (width or height), an error value is returned.
+    ///
     /// @note As a side effect, this changes the current
     ///     foreground color for subsequent operations.
     ///
-    /// @param x1 is the horizontal start of the line.
-    /// @param y1 is the vertical start of the line.
-    /// @param x2 is the horizontal end of the line.
-    /// @param y2 is the vertical end of the line.
-    /// @param radius1 defines the horizontal width of the curved corner.
-    /// @param radius2 defines the vertical width of the curved corner.
+    /// @param x1 is the horizontal start of the line and must be <= x2.
+    /// @param y1 is the vertical start of the line and must be <= y2.
+    /// @param x2 is the horizontal end of the line and must be >= x1.
+    /// @param y2 is the vertical end of the line and must be >= y1.
+    /// @param radius1 defines the horizontal width of the curved corner. Take care
+    ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
+    ///         is returned.
+    /// @param radius2 defines the vertical width of the curved corner. Take care
+    ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
+    ///         is returned.
     /// @param color defines the foreground color.
     /// @param fillit is optional to FILL the rectangle. default is NOFILL.
     /// @returns success/failure code. @see RetCode_t.
@@ -494,15 +516,24 @@
 
     /// Draw a rectangle with rounded corners using the specified color.
     ///
+    /// This draws a rounded rectangle. A numbers of checks are made on the values,
+    /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
+    /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
+    /// > 1/2 the length of that side (width or height), an error value is returned.
+    ///
     /// @note As a side effect, this changes the current
     ///     foreground color for subsequent operations.
     ///
-    /// @param x1 is the horizontal start of the line.
-    /// @param y1 is the vertical start of the line.
-    /// @param x2 is the horizontal end of the line.
-    /// @param y2 is the vertical end of the line.
-    /// @param radius1 defines the horizontal width of the curved corner.
-    /// @param radius2 defines the vertical width of the curved corner.
+    /// @param x1 is the horizontal start of the line and must be <= x2.
+    /// @param y1 is the vertical start of the line and must be <= y2.
+    /// @param x2 is the horizontal end of the line and must be >= x1.
+    /// @param y2 is the vertical end of the line and must be >= y1.
+    /// @param radius1 defines the horizontal width of the curved corner. Take care
+    ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
+    ///         is returned.
+    /// @param radius2 defines the vertical width of the curved corner. Take care
+    ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
+    ///         is returned.
     /// @param color defines the foreground color.
     /// @param fillit is optional to FILL the rectangle. default is NOFILL.
     /// @returns success/failure code. @see RetCode_t.
@@ -512,14 +543,21 @@
 
     /// Draw a rectangle with rounded corners.
     ///
-    /// Draws a rectangle with rounded corners using the foreground color setting.
+    /// This draws a rounded rectangle. A numbers of checks are made on the values,
+    /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
+    /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
+    /// > 1/2 the length of that side (width or height), an error value is returned.
     ///
-    /// @param x1 is the horizontal start of the line.
-    /// @param y1 is the vertical start of the line.
-    /// @param x2 is the horizontal end of the line.
-    /// @param y2 is the vertical end of the line.
-    /// @param radius1 defines the horizontal width of the curved corner.
-    /// @param radius2 defines the vertical width of the curved corner.
+    /// @param x1 is the horizontal start of the line and must be <= x2.
+    /// @param y1 is the vertical start of the line and must be <= y2.
+    /// @param x2 is the horizontal end of the line and must be >= x1.
+    /// @param y2 is the vertical end of the line and must be >= y1.
+    /// @param radius1 defines the horizontal width of the curved corner. Take care
+    ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
+    ///         is returned.
+    /// @param radius2 defines the vertical width of the curved corner. Take care
+    ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
+    ///         is returned.
     /// @param fillit is optional to FILL the rectangle. default is NOFILL.
     /// @returns success/failure code. @see RetCode_t.
     ///
@@ -532,7 +570,7 @@
     ///     foreground color for subsequent operations.
     ///
     /// @param x1 is the horizontal for point 1.
-    /// @param y1 is the vertical for point 1.
+    /// @param y1 is the vertical for point 1. 
     /// @param x2 is the horizontal for point 2.
     /// @param y2 is the vertical for point 2.
     /// @param x3 is the horizontal for point 3.