refs #5192 added some doc blocks and prevent the menu hooks from appearing in the documentation as they are deprecated

5 files changed, 17 insertions, 90 deletions

diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php
index ebdf22b5fd..4ffbe8f532 100644
--- a/core/Menu/MenuAbstract.php
+++ b/core/Menu/MenuAbstract.php
@@ -107,7 +107,7 @@ abstract class MenuAbstract extends Singleton
      * @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.
+     * @param bool|string $tooltip An optional tooltip to display or false to display the tooltip.
      * @api
      */
     public function add($menuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 50, $tooltip = false)
@@ -207,6 +207,7 @@ abstract class MenuAbstract extends Singleton
      * @param $mainMenuToEdit
      * @param $subMenuToEdit
      * @param $newUrl
+     * @api
      */
     public function editUrl($mainMenuToEdit, $subMenuToEdit, $newUrl)
     {
diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php
index eff86bd9c9..2d48cbeeae 100644
--- a/core/Menu/MenuAdmin.php
+++ b/core/Menu/MenuAdmin.php
@@ -41,8 +41,7 @@ class MenuAdmin extends MenuAbstract
      * @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
-     * @deprecated since version 2.3.0
+     * @deprecated since version 2.4.0. See {@link Piwik\Plugin\Menu} for new implementation.
      */
     public static function addEntry($adminMenuName, $url, $displayedForCurrentUser = true, $order = 20)
     {
@@ -59,25 +58,7 @@ class MenuAdmin extends MenuAbstract
         if (!$this->menu) {
 
             /**
-             * Triggered when collecting all available admin menu items. Subscribe to this event if you want
-             * to add one or more items to the Piwik admin menu.
-             *
-             * Menu items should be added via the {@link add()} method.
-             *
-             * **Example**
-             * 
-             *     use Piwik\Menu\MenuAdmin;
-             * 
-             *     public function addMenuItems()
-             *     {
-             *         MenuAdmin::getInstance()->add(
-             *             'MenuName',
-             *             'SubmenuName',
-             *             array('module' => 'MyPlugin', 'action' => 'index'),
-             *             $showOnlyIf = Piwik::hasUserSuperUserAccess(),
-             *             $order = 6
-             *         );
-             *     }
+             * @ignore
              */
             Piwik::postEvent('Menu.Admin.addItems', array());
 
@@ -113,7 +94,7 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * @deprecated since version 2.3.0
+     * @deprecated since version 2.4.0. See {@link Piwik\Plugin\Menu} for new implementation.
      */
     public static function removeEntry($menuName, $subMenuName = false)
     {
diff --git a/core/Menu/MenuMain.php b/core/Menu/MenuMain.php
index c078e2166d..9f422e755c 100644
--- a/core/Menu/MenuMain.php
+++ b/core/Menu/MenuMain.php
@@ -10,25 +10,8 @@ namespace Piwik\Menu;
 
 
 /**
- * Contains menu entries for the Main menu (the menu displayed under the Piwik logo).
- * Plugins can subscribe to the {@hook 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
- *         );
- *     }
- *
- * @api
+ * @deprecated since 2.4.0
+ * @see MenuReporting
  * @method static \Piwik\Menu\MenuMain getInstance()
  */
 class MenuMain extends MenuReporting
diff --git a/core/Menu/MenuReporting.php b/core/Menu/MenuReporting.php
index 18e9ffb657..bc791aa6a8 100644
--- a/core/Menu/MenuReporting.php
+++ b/core/Menu/MenuReporting.php
@@ -10,14 +10,14 @@ namespace Piwik\Menu;
 use Piwik\Piwik;
 
 /**
- * Contains menu entries for the Main menu (the menu displayed under the Piwik logo).
+ * Contains menu entries for the Reporting menu (the menu displayed under the Piwik logo).
  * Plugins can subscribe to the {@hook Menu.Reporting.addItems} event to add new pages to
- * the main menu.
+ * the reporting menu.
  *
  * **Example**
  *
  *     // add a new page in an observer to Menu.Admin.addItems
- *     public function addMainMenuItem()
+ *     public function addReportingMenuItem()
  *     {
  *         MenuReporting::getInstance()->add(
  *             'MyPlugin_MyTranslatedMenuCategory',
@@ -29,7 +29,7 @@ use Piwik\Piwik;
  *     }
  *
  * @api
- * @method static \Piwik\Menu\MenuMain getInstance()
+ * @method static \Piwik\Menu\MenuReporting getInstance()
  */
 class MenuReporting extends MenuAbstract
 {
@@ -41,7 +41,7 @@ class MenuReporting extends MenuAbstract
      */
     public function isUrlFound($url)
     {
-        $menu = MenuMain::getInstance()->getMenu();
+        $menu = $this->getMenu();
 
         foreach ($menu as $subMenus) {
             foreach ($subMenus as $subMenuName => $menuUrl) {
@@ -60,29 +60,10 @@ class MenuReporting extends MenuAbstract
      */
     public function getMenu()
     {
-        // We trigger the Event only once!
         if (!$this->menu) {
 
             /**
-             * Triggered when collecting all available reporting menu items. Subscribe to this event if you
-             * want to add one or more items to the Piwik reporting menu.
-             *
-             * Menu items should be added via the {@link add()} method.
-             *
-             * **Example**
-             *
-             *     use Piwik\Menu\MenuMain;
-             *
-             *     public function addMenuItems()
-             *     {
-             *         MenuMain::getInstance()->add(
-             *             'CustomMenuName',
-             *             'CustomSubmenuName',
-             *             array('module' => 'MyPlugin', 'action' => 'index'),
-             *             $showOnlyIf = Piwik::hasUserSuperUserAccess(),
-             *             $order = 6
-             *         );
-             *     }
+             * @ignore
              */
             Piwik::postEvent('Menu.Reporting.addItems', array());
 
diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php
index 5e664e9624..17cefa2135 100644
--- a/core/Menu/MenuTop.php
+++ b/core/Menu/MenuTop.php
@@ -45,8 +45,7 @@ class MenuTop extends MenuAbstract
      * @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
-     * @deprecated since version 2.3.0
+     * @deprecated since version 2.4.0. See {@link Piwik\Plugin\Menu} for new implementation.
      */
     public static function addEntry($topMenuName, $url, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false)
     {
@@ -58,7 +57,7 @@ class MenuTop extends MenuAbstract
     }
 
     /**
-     * @deprecated since version 2.3.0
+     * @deprecated since version 2.4.0. See {@link Piwik\Plugin\Menu} for new implementation.
      */
     public static function removeEntry($menuName, $subMenuName = false)
     {
@@ -73,6 +72,7 @@ class MenuTop extends MenuAbstract
      * @param boolean $displayedForCurrentUser
      * @param int $order
      * @param string $tooltip Tooltip to display.
+     * @api
      */
     public function addHtml($menuName, $data, $displayedForCurrentUser, $order, $tooltip)
     {
@@ -96,26 +96,7 @@ class MenuTop extends MenuAbstract
         if (!$this->menu) {
 
             /**
-             * Triggered when collecting all available menu items that are be displayed on the very top of every
-             * page, next to the login/logout links.
-             * 
-             * Subscribe to this event if you want to add one or more items to the top menu.
-             * 
-             * Menu items should be added via the {@link addEntry()} method.
-             *
-             * **Example**
-             * 
-             *     use Piwik\Menu\MenuTop;
-             *
-             *     public function addMenuItems()
-             *     {
-             *         MenuTop::addEntry(
-             *             'TopMenuName',
-             *             array('module' => 'MyPlugin', 'action' => 'index'),
-             *             $showOnlyIf = Piwik::hasUserSuperUserAccess(),
-             *             $order = 6
-             *         );
-             *     }
+             * @ignore
              */
             Piwik::postEvent('Menu.Top.addItems', array());