Diff: NWSWeather.h

Revision:

1:e077d6502c94

Parent:

0:4435c965d95d

Child:

2:eae60b64066e

--- a/NWSWeather.h	Sun Mar 16 15:37:16 2014 +0000
+++ b/NWSWeather.h	Sun Mar 16 16:03:57 2014 +0000
@@ -1,54 +1,43 @@
-
+/// @file NWSWeather.h
+/// This file contains the interface for gathering forecast from NWS.
+///
+/// @attention This program is copyright (c) 2014 by Smartware Computing, all 
+/// rights reserved.
+/// 
+/// This software, and/or material is the property of Smartware Computing. All
+/// use, disclosure, and/or reproduction not specifically authorized by Smartware
+/// Computing is prohibited.
+///
+/// This software may be freely used for non-commercial purposes, and any 
+/// derivative work shall carry the original copyright. The author of
+/// a derivative work shall make clear that it is a derivative work.
+///
+/// @author David Smart, Smartware Computing
+///
 #ifndef NWSWEATHER_H
 #define NWSWEATHER_H
 #include "mbed.h"
 #include "HTTPClient.h"
 
-/// Return code interpretation.
-typedef enum
-{
-    noerror,        ///< no error, or parameter has been updated.
-    nomemory,       ///< insufficient memory to complete operation.
-    noresponse,     ///< no response from server.
-    badparameter,   ///< bad parameter to function (typically out of range value).
-    noupdate,       ///< no update available.
-    noparamfound    ///< no parameter found.
-} NWSReturnCode_T;
-
-typedef enum
-{
-    isFloat,
-    isInt,
-    isString
-} TypeOf_T;
-
-typedef union
-{
-    float  fValue;      // ValueType 0
-    int    iValue;      // ValueType 1
-    char * sValue;      // ValueType 2
-} Value_T;
-
-typedef struct 
-{
-    char * name;
-    TypeOf_T typeis;
-    bool updated;
-    Value_T value;
-} XMLItem_T;
-
-
 /// NOAA's National Weather Service handler class.
 ///
 /// This class will fetch and parse weather data from an XML feed
 /// using a URL such as "http://www.weather.gov/data/current_obs/KALO.xml".
 ///
+/// @attention Proper use of this should follow the NWS guideline,
+///     which is to not request this data from the server more often than
+///     necessary, and ideally to recognize and use the suggested_pickup
+///     parameter for subsequent updates of the weather information. This
+///     class does not monitor the RTC so is unaware of the time of day. It
+///     is therefore up to the user to manage this recommended practice.
+///
 /// Only the essential parameters are gathered, which is generally those
 /// from which you can derive others. It turns out this is also most of the
 /// parameters.
-/// \li observation_time_rfc822
-/// \li        suggested_pickup
-/// \li suggested_pickup_period
+///
+/// \li observation_time_rfc822 - "Sun, 16 Mar 2014 09:54:00 -0500"
+/// \li        suggested_pickup - "15 minutes after the hour"
+/// \li suggested_pickup_period - 60 (minutes)
 /// \li                location
 /// \li                 weather
 /// \li                  temp_f
@@ -63,14 +52,50 @@
 /// \li             windchill_f
 /// \li             windchill_c
 /// \li           visibility_mi
-/// \li           icon_url_base
-/// \li           icon_url_name
+/// \li           icon_url_base - http://forecast.weather.gov/images/wtf/small/
+/// \li           icon_url_name - ovc.png (changes based on forecast)
 /// \li                latitude
 /// \li               longitude
 ///
 class NWSWeather
 {
 public:
+    /// Return code interpretation.
+    typedef enum
+    {
+        noerror,        ///< no error, or parameter has been updated.
+        nomemory,       ///< insufficient memory to complete operation.
+        noresponse,     ///< no response from server.
+        badparameter,   ///< bad parameter to function (typically out of range value).
+        noupdate,       ///< no update available.
+        noparamfound    ///< no parameter found.
+    } NWSReturnCode_T;
+    
+    /// Identifies the type of a parameter.
+    typedef enum
+    {
+        isFloat,        ///< this parameter is a floating point value.
+        isInt,          ///< this parameter is an integer.
+        isString        ///< this parameter is a string value.
+    } TypeOf_T;
+    
+    /// The union of available types.
+    typedef union
+    {
+        float  fValue;  ///< the floating point value
+        int    iValue;  ///< the integer value
+        char * sValue;  ///< the string value
+    } Value_T;
+    
+    /// The internal maintenance structure.
+    typedef struct 
+    {
+        char * name;
+        TypeOf_T typeis;
+        bool updated;
+        Value_T value;
+    } XMLItem_T;
+
 
     /// Constructor.
     ///
@@ -118,11 +143,12 @@
     /// get the weather data from the specified site.
     ///
     /// This does the work to fetch the weather data from the specified site,
-    /// using the baseurl established when the NWSWeather object is constructed.
+    /// using the baseurl established when the NWSWeather object was constructed,
+    /// or when it was modified with the setAlternateURL API.
     ///
     /// @param site is the site/location code of the site of interest.
-    /// @param responseSize sets the size of a temporarily allocated buffer
-    ///         into which the data is received.
+    /// @param responseSize hints to this class the size of a buffer it
+    ///         should temporarily allocate to receive and process the data.
     /// @param returns success/failure code. @see NWSReturnCode_T.
     ///
     NWSReturnCode_T get(const char * site, int responseSize = 3000);
@@ -137,12 +163,15 @@
     /// acquisition.
     ///
     /// @param i is the item of interest.
-    /// @param returns noerror if the parameter is up to date. @see NWSReturnCode_T.
+    /// @returns noerror if the parameter is up to date. @see NWSReturnCode_T.
     ///
     NWSReturnCode_T isUpdated(uint16_t i);
     
     /// get one of the weather parameters.
     ///
+    /// This fetches one of the available weather parameters by setting
+    /// user supplied pointers to reference the parameter.
+    ///
     /// @code
     /// // Iterate over each of the parameters
     /// for (i=0; i<wx.count(); i++) {
@@ -173,6 +202,10 @@
     
     /// get one of the weather parameters.
     ///
+    /// This searchs the parameter set for the named parameter, and if found
+    /// it will set the user supplied pointers to the value and type information
+    /// for that parameter.
+    ///
     /// @code
     /// TypeOf_T type; char * value;
     /// if (wx.getParam("temp_f", &type, value)) {
@@ -189,7 +222,8 @@
     
     /// Print to stdout the specified weather record.
     ///
-    /// Prints the specified record as a "Parmeter = value\r\n" string.
+    /// Prints the specified record as a "Parmeter = value\r\n" string, formatted
+    /// so that subsequent prints line up at the '=' sign.
     ///
     /// @param i specifies the record.
     ///
@@ -197,7 +231,7 @@
 
     /// Printa all the records to stdout.
     ///
-    /// calls PrintWeatherRecord for each parameter.
+    /// calls PrintWeatherRecord for each available parameter.
     ///
     void PrintAllWeatherRecords(void);