Cleanup phpdoc for forecast classses.

horde · Apr 2, 2014 · 39b4580 · 39b4580
1 parent e7c7049
commit 39b4580
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 23 deletions.
diff --git a/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/Base.php b/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/Base.php
@@ -19,7 +19,7 @@
  * @category Horde
  * @package  Service_Weather
  */
- class Horde_Service_Weather_Forecast_Base implements IteratorAggregate
+ abstract class Horde_Service_Weather_Forecast_Base implements IteratorAggregate
  {
     /**
      * The forecast properties as returned from the forecast request.
@@ -35,13 +35,6 @@ class Horde_Service_Weather_Forecast_Base implements IteratorAggregate
      */
     protected $_periods = array();
 
-    /**
-     * Parent Weather driver.
-     *
-     * @var Horde_Service_Weather_Base
-     */
-    public $weather;
-
     /**
      * Forecast type
      *
@@ -55,6 +48,20 @@ class Horde_Service_Weather_Forecast_Base implements IteratorAggregate
      */
     protected $_maxDays = 20;
 
+    /**
+     * Parent Weather driver.
+     *
+     * @var Horde_Service_Weather_Base
+     */
+    public $weather;
+
+    /**
+     * Array of supported "detailed" forecast fields. To be populated by
+     * concrete classes.
+     *
+     * @var array
+     */
+    public $fields = array();
 
     /**
      * Advertise how detailed the forecast period is.
@@ -85,21 +92,18 @@ public function __construct(
         $this->_type = $type;
     }
 
-    public function getIterator()
-    {
-        return new ArrayIterator(array_slice($this->_periods, 0, $this->_maxDays));
-    }
-
+    /**
+     * Return the forecast for the specified ordinal day.
+     *
+     * @param integer $day  The forecast day to return.
+     *
+     * @return Horde_Service_Weather_Period_Base
+     */
     public function getForecastDay($day)
     {
         return $this->_periods[$day];
     }
 
-    public function getForecastTime()
-    {
-        return false;
-    }
-
     /**
      * Limit the returned number of forecast days. Used for emulating a smaller
      * forecast length than the provider supports or for using one, longer
@@ -112,4 +116,21 @@ public function limitLength($days)
         $this->_maxDays = $days;
     }
 
+    /**
+     * Return the time of the forecast.
+     *
+     * @return Horde_Date  The time of the forecast.
+     */
+    abstract public function getForecastTime();
+
+    /**
+     * Return an ArrayIterator
+     *
+     * @return ArrayIterator
+     */
+    public function getIterator()
+    {
+        return new ArrayIterator(array_slice($this->_periods, 0, $this->_maxDays));
+    }
+
  }
diff --git a/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/WeatherUnderground.php b/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/WeatherUnderground.php
@@ -20,12 +20,19 @@
  */
  class Horde_Service_Weather_Forecast_WeatherUnderground extends Horde_Service_Weather_Forecast_Base
  {
-
+    /**
+     * @see Horde_Service_Weather_Forecast_Base::$fields
+     */
     public $fields = array(
         Horde_Service_Weather::FORECAST_FIELD_WIND,
         Horde_Service_Weather::FORECAST_FIELD_HUMIDITY,
         Horde_Service_Weather::FORECAST_FIELD_PRECIPITATION);
 
+    /**
+     * Const'r
+     *
+     * @see Horde_Service_Weather_Forecast_Base::__construct()
+     */
     public function __construct(
         $properties,
         Horde_Service_Weather_Base $weather,
@@ -41,13 +48,18 @@ public function __construct(
         }
     }
 
+    /**
+     * Return the forecast time.
+     *
+     * @see Horde_Service_Weather_Forecast_Base::getForecastTime()
+     */
     public function getForecastTime()
     {
         return new Horde_Date($this->_properties['txt_forecast']->date);
     }
 
     /**
-     * [_parse description]
+     * Parse the Std forecast data
      *
      * @throws Horde_Service_Weather_Exception
      */
@@ -62,9 +74,10 @@ protected function _parseStd()
         }
     }
 
+    // @TODO: Use the hourly forecast to maybe get a "day"/"night"
     protected function _parseHourly()
     {
-        // @TODO: Use the hourly forecast to maybe get a "day"/"night"
+        throw Horde_Exception('Not currently implemented.');
     }
 
  }
diff --git a/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/Wwo.php b/framework/Service_Weather/lib/Horde/Service/Weather/Forecast/Wwo.php
@@ -21,9 +21,16 @@
  class Horde_Service_Weather_Forecast_Wwo extends Horde_Service_Weather_Forecast_Base
  {
 
-    public $fields = array(
-        Horde_Service_Weather::FORECAST_FIELD_WIND);
+    /**
+     * @see Horde_Service_Weather_Forecast_Base::$fields
+     */
+    public $fields = array(Horde_Service_Weather::FORECAST_FIELD_WIND);
 
+    /**
+     * Const'r
+     *
+     * @see Horde_Service_Weather_Forecast_Base::__construct()
+     */
     public function __construct(
         $properties,
         Horde_Service_Weather_Base $weather,
@@ -33,6 +40,13 @@ public function __construct(
         $this->_parseStd();
     }
 
+    /**
+     * Return the forecast time. Note that Wwo doesn't provide the validity time
+     * for the forecast, so we use the last known station time. File this under
+     * the "good enough" file.
+     *
+     * @see Horde_Service_Weather_Forecast_Base::getForecastTime()
+     */
     public function getForecastTime()
     {
         return new Horde_Date($this->weather->getStation()->time);