Refs #4200 revised event docs for core/* files.

3 files changed, 54 insertions, 51 deletions

diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php
index eedd155b11..e58e964b1f 100644
--- a/core/Menu/MenuAdmin.php
+++ b/core/Menu/MenuAdmin.php
@@ -60,24 +60,25 @@ class MenuAdmin extends MenuAbstract
         if (!$this->menu) {
 
             /**
-             * This event is triggered to collect all available admin menu items. Subscribe to this event if you want
-             * to add one or more items to the Piwik admin menu. Just define the name of your menu item as well as a
-             * controller and an action that should be executed once a user selects your menu item. It is also possible
-             * to display the item only for users having a specific role.
+             * 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.
              *
-             * Example:
-             * ```
-             * public function addMenuItems()
-             * {
-             *     MenuAdmin::getInstance()->add(
-             *         'MenuName',
-             *         'SubmenuName',
-             *         array('module' => 'MyPlugin', 'action' => 'index'),
-             *         Piwik::isUserIsSuperUser(),
-             *         $order = 6
-             *     );
-             * }
-             * ```
+             * Menu items should be added via the [Menu::add](#) method.
+             *
+             * **Example**
+             * 
+             *     use Piwik\Menu\MenuAdmin;
+             * 
+             *     public function addMenuItems()
+             *     {
+             *         MenuAdmin::getInstance()->add(
+             *             'MenuName',
+             *             'SubmenuName',
+             *             array('module' => 'MyPlugin', 'action' => 'index'),
+             *             $showOnlyIf = Piwik::isUserIsSuperUser(),
+             *             $order = 6
+             *         );
+             *     }
              */
             Piwik::postEvent('Menu.Admin.addItems');
         }
diff --git a/core/Menu/MenuMain.php b/core/Menu/MenuMain.php
index 490eaece4c..9aecbd7f74 100644
--- a/core/Menu/MenuMain.php
+++ b/core/Menu/MenuMain.php
@@ -66,24 +66,25 @@ class MenuMain extends MenuAbstract
         if (!$this->menu) {
 
             /**
-             * This event is triggered to collect all available reporting menu items. Subscribe to this event if you
-             * want to add one or more items to the Piwik reporting menu. Just define the name of your menu item as
-             * well as a controller and an action that should be executed once a user selects your menu item. It is
-             * also possible to display the item only for users having a specific role.
+             * 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 [Menu::add](#) method.
              *
-             * Example:
-             * ```
-             * public function addMenuItems()
-             * {
-             *     \Piwik\Menu\Main::getInstance()->add(
-             *         'CustomMenuName',
-             *         'CustomSubmenuName',
-             *         array('module' => 'MyPlugin', 'action' => 'index'),
-             *         Piwik::isUserIsSuperUser(),
-             *         $order = 6
-             *     );
-             * }
-             * ```
+             * **Example**
+             * 
+             *     use Piwik\Menu\Main;
+             * 
+             *     public function addMenuItems()
+             *     {
+             *         Main::getInstance()->add(
+             *             'CustomMenuName',
+             *             'CustomSubmenuName',
+             *             array('module' => 'MyPlugin', 'action' => 'index'),
+             *             $showOnlyIf = Piwik::isUserIsSuperUser(),
+             *             $order = 6
+             *         );
+             *     }
              */
             Piwik::postEvent('Menu.Reporting.addItems');
         }
diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php
index 376985823e..8da4140206 100644
--- a/core/Menu/MenuTop.php
+++ b/core/Menu/MenuTop.php
@@ -90,24 +90,25 @@ class MenuTop extends MenuAbstract
         if (!$this->menu) {
 
             /**
-             * This event is triggered to collect all available menu items that should be displayed on the very top next
-             * to login/logout, API and other menu items. Subscribe to this event if you want to add one or more items.
-             * It's fairly easy. Just define the name of your menu item as well as a controller and an action that
-             * should be executed once a user selects your menu item. It is also possible to display the item only for
-             * users having a specific role.
+             * 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 [MenuTop::addEntry](#addEntry) method.
              *
-             * Example:
-             * ```
-             * public function addMenuItems()
-             * {
-             *     MenuTop::addEntry(
-             *         'TopMenuName',
-             *         array('module' => 'MyPlugin', 'action' => 'index'),
-             *         Piwik::isUserIsSuperUser(),
-             *         $order = 6
-             *     );
-             * }
-             * ```
+             * **Example**
+             * 
+             *     use Piwik\Menu\MenuTop;
+             *
+             *     public function addMenuItems()
+             *     {
+             *         MenuTop::addEntry(
+             *             'TopMenuName',
+             *             array('module' => 'MyPlugin', 'action' => 'index'),
+             *             $showOnlyIf = Piwik::isUserIsSuperUser(),
+             *             $order = 6
+             *         );
+             *     }
              */
             Piwik::postEvent('Menu.Top.addItems');
         }