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

4 files changed, 93 insertions, 28 deletions

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