Refs #4200, document core/Menu/*.php and core/Period/Range.php and remove Range::removePeriod and replace w/ Date::addPeriod.

10 files changed, 120 insertions, 78 deletions

diff --git a/core/ArchiveProcessor.php b/core/ArchiveProcessor.php
index 167b930fe5..a9a96b2b3f 100644
--- a/core/ArchiveProcessor.php
+++ b/core/ArchiveProcessor.php
@@ -505,6 +505,7 @@ abstract class ArchiveProcessor
                 $clean[] = array($newName, $value);
             }
             $this->archiveWriter->insertBulkRecords($clean);
+            return;
         }
 
         $values = $this->compress($values);
diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php
index c141e617bb..e5293d5733 100644
--- a/core/Menu/MenuAbstract.php
+++ b/core/Menu/MenuAbstract.php
@@ -15,6 +15,12 @@ use Piwik\Plugins\SitesManager\API;
 use Piwik\Singleton;
 
 /**
+ * Base class for classes that manage one of Piwik's menus.
+ * 
+ * There are three menus in Piwik, the main menu, the top menu and the admin menu.
+ * Each menu has a class that manages the rendering of it. Each class invokes
+ * a different event to allow plugins to add new menu items.
+ * 
  * @package Piwik_Menu
  * @static \Piwik\Menu\MenuAbstract getInstance()
  */
@@ -45,12 +51,15 @@ abstract class MenuAbstract extends Singleton
     /**
      * Adds a new entry to the menu.
      *
-     * @param string $menuName
-     * @param string $subMenuName
-     * @param string $url
-     * @param bool $displayedForCurrentUser
-     * @param int $order
-     * @param bool|string $tooltip Tooltip to display.
+     * @param string $menuName The menu's category name. Can be a translation token.
+     * @param string $subMenuName The menu item's name. Can be a translation token.
+     * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters
+     *                          that can be used to build the URL.
+     * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the
+     *                                         current user. If false, the entry will not be added.
+     * @param int $order The order hint.
+     * @param false|string $tooltip An optional tooltip to display.
+     * @api
      */
     public function add($menuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 50, $tooltip = false)
     {
@@ -224,4 +233,4 @@ abstract class MenuAbstract extends Singleton
         }
         return ($itemOne['_order'] < $itemTwo['_order']) ? -1 : 1;
     }
-}
+}
\ No newline at end of file
diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php
index eb3576d37e..eedd155b11 100644
--- a/core/Menu/MenuAdmin.php
+++ b/core/Menu/MenuAdmin.php
@@ -13,17 +13,36 @@ namespace Piwik\Menu;
 use Piwik\Piwik;
 
 /**
+ * Contains menu entries for the Admin menu. Plugins can subscribe to the 
+ * [Menu.Admin.addItems](#) event to add new pages to the admin menu.
+ * 
+ * **Example**
+ * 
+ *     // add a new page in an observer to Menu.Admin.addItems
+ *     public function addAdminMenuItem()
+ *     {
+ *         MenuAdmin::getInstance()->add(
+ *             'MyPlugin_MyTranslatedAdminMenuCategory',
+ *             'MyPlugin_MyTranslatedAdminPageName',
+ *             array('module' => 'MyPlugin', 'action' => 'index'),
+ *             Piwik::isUserHasSomeAdminAccess(),
+ *             $order = 2
+ *         );
+ *     }
+ * 
  * @package Piwik_Menu
  */
 class MenuAdmin extends MenuAbstract
 {
     /**
-     * Adds a new AdminMenu entry.
+     * Adds a new AdminMenu entry under the 'Settings' category.
      *
-     * @param string $adminMenuName
-     * @param string $url
-     * @param boolean $displayedForCurrentUser
-     * @param int $order
+     * @param string $adminMenuName The name of the admin menu entry. Can be a translation token.
+     * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters
+     *                          that can be used to build the URL.
+     * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the
+     *                                         current user. If false, the entry will not be added.
+     * @param int $order The order hint.
      * @api
      */
     public static function addEntry($adminMenuName, $url, $displayedForCurrentUser = true, $order = 20)
@@ -70,7 +89,7 @@ class MenuAdmin extends MenuAbstract
      *
      * @return boolean
      */
-    function getCurrentAdminMenuName()
+    public function getCurrentAdminMenuName()
     {
         $menu = MenuAdmin::getInstance()->getMenu();
         $currentModule = Piwik::getModule();
@@ -87,5 +106,4 @@ class MenuAdmin extends MenuAbstract
         }
         return false;
     }
-}
-
+}
\ No newline at end of file
diff --git a/core/Menu/MenuMain.php b/core/Menu/MenuMain.php
index 4146559fcd..490eaece4c 100644
--- a/core/Menu/MenuMain.php
+++ b/core/Menu/MenuMain.php
@@ -11,9 +11,27 @@
 namespace Piwik\Menu;
 use Piwik\Piwik;
 
-
 /**
+ * Contains menu entries for the Main menu (the menu displayed under the Piwik logo).
+ * Plugins can subscribe to the [Menu.Reporting.addItems](#) event to add new pages to
+ * the main menu.
+ * 
+ * **Example**
+ * 
+ *     // add a new page in an observer to Menu.Admin.addItems
+ *     public function addMainMenuItem()
+ *     {
+ *         MenuMain::getInstance()->add(
+ *             'MyPlugin_MyTranslatedMenuCategory',
+ *             'MyPlugin_MyTranslatedMenuName',
+ *             array('module' => 'MyPlugin', 'action' => 'index'),
+ *             Piwik::isUserHasSomeAdminAccess(),
+ *             $order = 2
+ *         );
+ *     }
+ * 
  * @package Piwik_Menu
+ * @api
  */
 class MenuMain extends MenuAbstract
 {
@@ -71,5 +89,4 @@ class MenuMain extends MenuAbstract
         }
         return parent::getMenu();
     }
-}
-
+}
\ No newline at end of file
diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php
index ab2d312799..376985823e 100644
--- a/core/Menu/MenuTop.php
+++ b/core/Menu/MenuTop.php
@@ -13,6 +13,24 @@ use Piwik\Piwik;
 
 
 /**
+ * Contains menu entries for the Top menu (the menu at the very top of the page).
+ * Plugins can subscribe to the [Menu.Top.addItems](#) event to add new pages to
+ * the top menu.
+ * 
+ * **Example**
+ * 
+ *     // add a new page in an observer to Menu.Admin.addItems
+ *     public function addTopMenuItem()
+ *     {
+ *         MenuTop::getInstance()->add(
+ *             'MyPlugin_MyTranslatedMenuCategory',
+ *             'MyPlugin_MyTranslatedMenuName',
+ *             array('module' => 'MyPlugin', 'action' => 'index'),
+ *             Piwik::isUserHasSomeAdminAccess(),
+ *             $order = 2
+ *         );
+ *     }
+ * 
  * @package Piwik_Menu
  */
 class MenuTop extends MenuAbstract
@@ -20,20 +38,23 @@ class MenuTop extends MenuAbstract
     /**
      * Adds a new entry to the TopMenu.
      *
-     * @param string $topMenuName
-     * @param string $data
-     * @param boolean $displayedForCurrentUser
-     * @param int $order
-     * @param bool $isHTML
-     * @param bool|string $tooltip Tooltip to display.
+     * @param string $topMenuName The menu item name. Can be a translation token.
+     * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters
+     *                          that can be used to build the URL. If `$isHTML` is true, this can be a string with
+     *                          HTML that is simply embedded.
+     * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the
+     *                                         current user. If false, the entry will not be added.
+     * @param int $order The order hint.
+     * @param bool $isHTML Whether `$url` is an HTML string or a URL that will be rendered as a link.
+     * @param bool|string $tooltip Optional tooltip to display.
      * @api
      */
-    public static function addEntry($topMenuName, $data, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false)
+    public static function addEntry($topMenuName, $url, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false)
     {
         if ($isHTML) {
-            MenuTop::getInstance()->addHtml($topMenuName, $data, $displayedForCurrentUser, $order, $tooltip);
+            MenuTop::getInstance()->addHtml($topMenuName, $url, $displayedForCurrentUser, $order, $tooltip);
         } else {
-            MenuTop::getInstance()->add($topMenuName, null, $data, $displayedForCurrentUser, $order, $tooltip);
+            MenuTop::getInstance()->add($topMenuName, null, $url, $displayedForCurrentUser, $order, $tooltip);
         }
     }
 
@@ -92,4 +113,4 @@ class MenuTop extends MenuAbstract
         }
         return parent::getMenu();
     }
-}
+}
\ No newline at end of file
diff --git a/core/Period/Day.php b/core/Period/Day.php
index 61d2809ef6..a08bdf008f 100644
--- a/core/Period/Day.php
+++ b/core/Period/Day.php
@@ -17,7 +17,6 @@ use Piwik\Piwik;
 /**
  * @package Piwik
  * @subpackage Period
- * @api
  */
 class Day extends Period
 {
diff --git a/core/Period/Month.php b/core/Period/Month.php
index b7fbf04346..ecbd41f751 100644
--- a/core/Period/Month.php
+++ b/core/Period/Month.php
@@ -16,7 +16,6 @@ use Piwik\Piwik;
 /**
  * @package Piwik
  * @subpackage Period
- * @api
  */
 class Month extends Period
 {
diff --git a/core/Period/Range.php b/core/Period/Range.php
index 3b7a429e48..e1bfa1f7ac 100644
--- a/core/Period/Range.php
+++ b/core/Period/Range.php
@@ -17,7 +17,15 @@ use Piwik\Period;
 use Piwik\Piwik;
 
 /**
- * from a starting date to an ending date
+ * Arbitrary date range representation.
+ * 
+ * This class represents a period that contains a list of consecutive days as subperiods
+ * It is created when the **period** query parameter is set to **range** and is used
+ * to calculate the subperiods of multiple period requests (eg, when period=day and
+ * date=2007-07-24,2013-11-15).
+ * 
+ * The range period differs from other periods mainly in that since it is arbitrary,
+ * range periods are not archived by the archive.php cron script.
  *
  * @package Piwik
  * @subpackage Period
@@ -28,10 +36,14 @@ class Range extends Period
     protected $label = 'range';
 
     /**
-     * @param string $strPeriod
-     * @param string $strDate
-     * @param string $timezone
-     * @param bool|Date $today
+     * Constructor.
+     * 
+     * @param string $strPeriod The type of period each subperiod is. Either `'day'`, `'week'`,
+     *                          `'month'` or `'year'`.
+     * @param string $strDate The date range, eg, `'2007-07-24,2013-11-15'`.
+     * @param string $timezone The timezone to use, eg, `'UTC'`.
+     * @param bool|Date $today The date to use as _today_. Defaults to `Date::factory('today', $timzeone)`.
+     * @api
      */
     public function __construct($strPeriod, $strDate, $timezone = 'UTC', $today = false)
     {
@@ -46,7 +58,7 @@ class Range extends Period
     }
 
     /**
-     * Returns the current period as a localized short string
+     * Returns the current period as a localized short string.
      *
      * @return string
      */
@@ -63,7 +75,7 @@ class Range extends Period
     }
 
     /**
-     * Returns the current period as a localized long string
+     * Returns the current period as a localized long string.
      *
      * @return string
      */
@@ -98,39 +110,6 @@ class Range extends Period
         return $out;
     }
 
-    /**
-     *
-     * @param string $period
-     * @param Date $date
-     * @param int $n
-     * @throws Exception
-     * @return Date
-     */
-    static public function removePeriod($period, Date $date, $n)
-    {
-        switch ($period) {
-            case 'day':
-                $startDate = $date->subDay($n);
-                break;
-
-            case 'week':
-                $startDate = $date->subDay($n * 7);
-                break;
-
-            case 'month':
-                $startDate = $date->subMonth($n);
-                break;
-
-            case 'year':
-                $startDate = $date->subMonth(12 * $n);
-                break;
-            default:
-                throw new Exception('The period parameter is invalid');
-                break;
-        }
-        return $startDate;
-    }
-
     protected function getMaxN($lastN)
     {
         switch ($this->strPeriod) {
@@ -192,7 +171,7 @@ class Range extends Period
             if ($lastOrPrevious == 'last') {
                 $endDate = $defaultEndDate;
             } elseif ($lastOrPrevious == 'previous') {
-                $endDate = self::removePeriod($period, $defaultEndDate, 1);
+                $endDate = $defaultEndDate->addPeriod(-1, $period);
             }
 
             $lastN = $this->getMaxN($lastN);
@@ -201,7 +180,7 @@ class Range extends Period
             $lastN--;
             $lastN = abs($lastN);
 
-            $startDate = self::removePeriod($period, $endDate, $lastN);
+            $startDate = $endDate->addPeriod(-$lastN, $period);
         } elseif ($dateRange = Range::parseDateRange($this->strDate)) {
             $strDateStart = $dateRange[1];
             $strDateEnd = $dateRange[2];
@@ -341,7 +320,7 @@ class Range extends Period
         // set end date to start of end period since we're comparing against start date.
         $endDate = $endSubperiod->getDateStart();
         while ($endDate->isLater($startDate)) {
-            $endDate = self::removePeriod($period, $endDate, 1);
+            $endDate = $endDate->addPeriod(-1, $period);
             $subPeriod = Period::factory($period, $endDate);
             $arrayPeriods[] = $subPeriod;
         }
@@ -359,6 +338,7 @@ class Range extends Period
      *
      * @return array An array with two elements, a string for the date before $date and
      *               a Period instance for the period before $date.
+     * @api
      */
     public static function getLastDate($date = false, $period = false)
     {
@@ -378,12 +358,12 @@ class Range extends Period
             {
                 $rangePeriod = new Range($period, $date);
 
-                $lastStartDate = Range::removePeriod($period, $rangePeriod->getDateStart(), $n = 1);
-                $lastEndDate = Range::removePeriod($period, $rangePeriod->getDateEnd(), $n = 1);
+                $lastStartDate = $rangePeriod->getDateStart()->addPeriod(-1, $period);
+                $lastEndDate = $rangePeriod->getDateEnd()->addPeriod(-1, $period);
 
                 $strLastDate = "$lastStartDate,$lastEndDate";
             } else {
-                $lastPeriod = Range::removePeriod($period, Date::factory($date), $n = 1);
+                $lastPeriod = Date::factory($date)->addPeriod(-1, $period);
                 $strLastDate = $lastPeriod->toString();
             }
         }
diff --git a/core/Period/Week.php b/core/Period/Week.php
index aeb8640d3c..322fd5b706 100644
--- a/core/Period/Week.php
+++ b/core/Period/Week.php
@@ -17,7 +17,6 @@ use Piwik\Piwik;
 /**
  * @package Piwik
  * @subpackage Period
- * @api
  */
 class Week extends Period
 {
diff --git a/core/Period/Year.php b/core/Period/Year.php
index 4bad292180..85c4e44a3c 100644
--- a/core/Period/Year.php
+++ b/core/Period/Year.php
@@ -16,7 +16,6 @@ use Piwik\Period;
 /**
  * @package Piwik
  * @subpackage Period
- * @api
  */
 class Year extends Period
 {