Diff: DisplayDefs.h

Revision:

167:8aa3fb2a5a31

Parent:

125:7a0b70f56550

--- a/DisplayDefs.h	Sun Feb 24 19:28:26 2019 +0000
+++ b/DisplayDefs.h	Tue Feb 26 19:52:57 2019 +0000
@@ -1,11 +1,23 @@
 #ifndef DISPLAYDEFS_H
 #define DISPLAYDEFS_H
 
+/// A Macro to define a @ref color_t value from independent values of Red, Green, and Blue.
+///
+/// This macro accepts 3 parameters, each with a range of 0 to 0xFF.
+/// Not all of the bits are used as it creates a 16-bit color from from 24-bits
+/// of information.
+///
+/// @param r is the Red component, ranging from 0 no-Red to 0xFF maximum-Red
+/// @param g is the Green component, ranging from 0 no-Red to 0xFF maximum-Green
+/// @param b is the Blue component, ranging from 0 no-Red to 0xFF maximum-Blue
+///
 #define RGB(r,g,b) ( ((r<<8)&0xF800) | ((g<<3)&0x07E0) | (b>>3) )
 
-
-/// Return values from functions. Use this number, or use the 
-/// lookup function to get a text string. @see GetErrorMessage.
+/// Return values from numerous APIs.
+///
+/// This is the return value from various functions. Compare the return value
+/// to the possibilities in this definition, or use the @ref RA8875::GetErrorMessage() 
+/// function to translate a @ref RetCode_t value into a text string.
 ///
 typedef enum
 {
@@ -22,8 +34,15 @@
     LastErrCode,            // Private marker.
 } RetCode_t;
 
-/// return values from TouchPanelReadable, TouchPanelA2DRaw, TouchPanelA2DFiltered.
-/// @see TouchPanelReadable.
+/// Touch API Return values.
+///
+/// This is the return value from various functions:
+/// * @ref RA8875::TouchCode()
+/// * @ref RA8875::TouchPanelReadable()
+/// * @ref RA8875::TouchPanelA2DRaw()
+/// * @ref RA8875::TouchPanelA2DFiltered()
+/// * @ref RA8875::TouchPanelGet() 
+///
 typedef enum
 {
     no_touch,               ///< no touch is detected
@@ -34,26 +53,35 @@
 } TouchCode_t;
 
 /// 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.
+/// which can range from -N to +N (even as the screen is always defined in the
+/// range of 0 to +n). See also @ref textloc_t.
+///
 typedef int16_t loc_t;
 
 /// Data type that manages text locations, which are row or column values in
-/// units of character, not pixel. @see loc_t.
+/// units of character, not pixel. See also @ref loc_t.
+///
 typedef uint16_t textloc_t;
 
 /// type that manages dimensions of width or height, which range from 0 to N.
+///
+/// @note that a dimension cannot be negative.
+///
 typedef uint16_t dim_t;
 
 /// type that manages x,y pairs
+///
 typedef struct
 {
     loc_t x;             ///< x value in the point
     loc_t y;             ///< y value in the point
 } point_t;
 
-/// 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.
+/// Data type that manages rectangles, which are pairs of points. 
+///
+/// @note It is recommended that p1 contains the top-left point and p2 contains 
+/// the bottom-right point, even though it should not matter.
+///
 typedef struct
 {
     point_t p1;         ///< p1 defines one point on the rectangle
@@ -64,6 +92,7 @@
 ///
 /// 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;         ///< calibration factor, see source for details
@@ -75,14 +104,11 @@
     int32_t Divider;    ///< calibration factor, see source for details
 } tpMatrix_t;
 
-/// color type definition to let the compiler help keep us honest.
+/// color type definition to let the compiler type-check parameters that
+/// are passed to or returned from APIs that use color.
 /// 
-/// colors can be defined with the RGB(r,g,b) macro, and there
-/// are a number of predefined colors:
-/// - Black,    Blue,       Green,       Cyan,
-/// - Red,      Magenta,    Brown,       Gray,
-/// - Charcoal, BrightBlue, BrightGreen, BrightCyan,
-/// - Orange,   Pink,       Yellow,      White
+/// colors can be easily defined with the @ref RGB(r,g,b) macro, or from 
+/// the @ref PredefinedColors.
 ///
 typedef uint16_t color_t;