Refs #4200, documented several more classes.

1 files changed, 93 insertions, 47 deletions

diff --git a/core/Period.php b/core/Period.php
index 4848086a04..f56d7df24e 100644
--- a/core/Period.php
+++ b/core/Period.php
@@ -11,6 +11,7 @@
 namespace Piwik;
 
 use Exception;
+use Piwik\Date;
 use Piwik\Period\Day;
 use Piwik\Period\Month;
 use Piwik\Period\Range;
@@ -18,8 +19,30 @@ use Piwik\Period\Week;
 use Piwik\Period\Year;
 
 /**
+ * Date range representation.
+ * 
+ * Piwik allows users to view aggregated statistics for each day and for date
+ * ranges consisting of several days. When requesting data, a _date_ string and
+ * a _period_ string must be used to specify the date range to view statistics
+ * for. This is the class that Piwik uses to represent and manipulate those
+ * date ranges.
+ * 
+ * There are five types of periods in Piwik: day, week, month, year and range,
+ * where **range** is any date range. The reason the other periods exist instead
+ * of just **range** is that Piwik will archive for days, weeks, months and years
+ * periodically, while every other date range is archived on-demand.
+ * 
+ * ### Examples
+ * 
+ * **Building a period from 'date' and 'period' query parameters**
+ * 
+ *     $date = Common::getRequestVar('date', null, 'string');
+ *     $period = Common::getRequestVar('period', null, 'string');
+ *     $periodObject = Period::advancedFactory($period, $date);
+ * 
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 abstract class Period
 {
@@ -39,22 +62,25 @@ abstract class Period
      * @var Date
      */
     protected $date = null;
-    static protected $errorAvailablePeriods = 'day, week, month, year, range';
 
     /**
-     * Constructor
+     * Constructor.
+     * 
      * @param Date $date
      */
-    public function __construct($date)
+    public function __construct(Date $date)
     {
-        $this->checkInputDate($date);
         $this->date = clone $date;
     }
 
     /**
-     * @param string $strPeriod "day", "week", "month", "year"
-     * @param Date $date Date object
-     * @throws Exception
+     * Creates a new Period instance with a period ID and Date instance.
+     * 
+     * Note: This method cannot create Range periods.
+     * 
+     * @param string $strPeriod `"day"`, `"week"`, `"month"`, `"year"`
+     * @param Date $date A date within the period.
+     * @throws Exception If `$strPeriod` is invalid.
      * @return \Piwik\Period
      */
     static public function factory($strPeriod, Date $date)
@@ -77,23 +103,24 @@ abstract class Period
                 break;
 
             default:
-                throw new Exception(Piwik::translateException('General_ExceptionInvalidPeriod', array($strPeriod, self::$errorAvailablePeriods)));
+                $message = Piwik::translateException(
+                    'General_ExceptionInvalidPeriod', array($strPeriod, 'day, week, month, year, range'));
+                throw new Exception($message);
                 break;
         }
     }
 
     /**
-     * Indicate if $dateString and $period correspond to multiple periods
+     * Returns true $dateString and $period correspond to multiple periods.
      *
      * @static
-     * @param  $dateString
-     * @param  $period
+     * @param  $dateString The `'date'` query parameter value.
+     * @param  $period The `'period'` query parameter value.
      * @return boolean
      */
     public static function isMultiplePeriod($dateString, $period)
     {
-        return
-            is_string($dateString)
+        return is_string($dateString)
             && (preg_match('/^(last|previous){1}([0-9]*)$/D', $dateString, $regs)
                 || Range::parseDateRange($dateString))
             && $period != 'range';
@@ -106,11 +133,11 @@ abstract class Period
      * and range to the API methods can directly be forwarded to this factory
      * method in order to get a suitable instance of Period.
      *
-     * @param string $strPeriod "day", "week", "month", "year", "range"
-     * @param string $strDate
+     * @param string $strPeriod `"day"`, `"week"`, `"month"`, `"year"`, `"range"`
+     * @param string $strDate The `'date'` query parameter value.
      * @return \Piwik\Period
      */
-    static public function advancedFactory($strPeriod, $strDate)
+    public static function advancedFactory($strPeriod, $strDate)
     {
         if (Period::isMultiplePeriod($strDate, $strPeriod) || $strPeriod == 'range') {
             return new Range($strPeriod, $strDate);
@@ -124,7 +151,8 @@ abstract class Period
      *
      * @param string $timezone
      * @param string $period The period string: day, week, month, year, range
-     * @param string $date The date or date range string.
+     * @param string $date The date or date range string. Can be a special value including
+     *                     `'now'`, `'today'`, `'yesterday'`, `'yesterdaySameTime'`.
      * @return \Piwik\Period
      */
     public static function makePeriodFromQueryParams($timezone, $period, $date)
@@ -150,9 +178,9 @@ abstract class Period
     }
 
     /**
-     * Returns the first day of the period
+     * Returns the first day of the period.
      *
-     * @return Date First day of the period
+     * @return Date
      */
     public function getDateStart()
     {
@@ -173,9 +201,9 @@ abstract class Period
     }
 
     /**
-     * Returns the last day of the period ; can be a date in the future
+     * Returns the last day of the period.
      *
-     * @return Date Last day of the period
+     * @return Date
      */
     public function getDateEnd()
     {
@@ -195,14 +223,20 @@ abstract class Period
         return $currentPeriod->getDate();
     }
 
+    /**
+     * Returns the period ID.
+     * 
+     * @return int A integer unique to this type of period.
+     */
     public function getId()
     {
         return Piwik::$idPeriods[$this->getLabel()];
     }
 
     /**
-     * Returns the label for the current period
-     * @return string
+     * Returns the label for the current period.
+     * 
+     * @return string `"day"`, `"week"`, `"month"`, `"year"`, `"range"`
      */
     public function getLabel()
     {
@@ -217,27 +251,14 @@ abstract class Period
         return $this->date;
     }
 
-    /**
-     * Checks if the given date is an instance of Date
-     *
-     * @param Date $date
-     *
-     * @throws Exception
-     */
-    protected function checkInputDate($date)
-    {
-        if (!($date instanceof Date)) {
-            throw new Exception("The date must be a Date object. " . var_export($date, true));
-        }
-    }
-
     protected function generate()
     {
         $this->subperiodsProcessed = true;
     }
 
     /**
-     * Returns the number of available subperiods
+     * Returns the number of available subperiods.
+     * 
      * @return int
      */
     public function getNumberOfSubperiods()
@@ -249,9 +270,9 @@ abstract class Period
     }
 
     /**
-     * Returns Period_Day for a period made of days (week, month),
-     *            Period_Month for a period made of months (year)
-     *
+     * Returns the set of Period instances that together make up this period. For a year,
+     * this would be 12 months. For a month this would be 28-31 days. Etc.
+     * 
      * @return Period[]
      */
     public function getSubperiods()
@@ -275,12 +296,10 @@ abstract class Period
     }
 
     /**
-     * Returns a string representing the current period
-     * Given param will be used to format the returned value
+     * Returns a list of strings representing the current period.
      *
-     * @param string $format
-     *
-     * @return array
+     * @param string $format The format of each individual day.
+     * @return array An array of string dates that this period consists of.
      */
     public function toString($format = "Y-m-d")
     {
@@ -294,6 +313,11 @@ abstract class Period
         return $dateString;
     }
 
+    /**
+     * See [toString](#toString).
+     * 
+     * @return string
+     */
     public function __toString()
     {
         return implode(",", $this->toString());
@@ -307,14 +331,36 @@ abstract class Period
         return $this->date->toString($part);
     }
 
+    /**
+     * Returns a pretty string describing this period.
+     * 
+     * @return string
+     */
     abstract public function getPrettyString();
 
+    /**
+     * Returns a short string description of this period that is localized with the currently used
+     * language.
+     * 
+     * @return string
+     */
     abstract public function getLocalizedShortString();
 
+    /**
+     * Returns a long string description of this period that is localized with the currently used
+     * language.
+     * 
+     * @return string
+     */
     abstract public function getLocalizedLongString();
 
+    /**
+     * Returns a succinct string describing this period.
+     * 
+     * @return string eg, `'2012-01-01,2012-01-31'`.
+     */
     public function getRangeString()
     {
         return $this->getDateStart()->toString("Y-m-d") . "," . $this->getDateEnd()->toString("Y-m-d");
     }
-}
+}
\ No newline at end of file