refs #4199 documented some more events

3 files changed, 63 insertions, 0 deletions

diff --git a/core/Menu/Admin.php b/core/Menu/Admin.php
index 67b9187d8c..ddf6462da2 100644
--- a/core/Menu/Admin.php
+++ b/core/Menu/Admin.php
@@ -39,6 +39,27 @@ class Admin extends MenuAbstract
     public function get()
     {
         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. 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.
+             *
+             * Example:
+             * ```
+             * public function addMenuItems()
+             * {
+             *     Piwik_AddAdminSubMenu(
+             *         'MenuName',
+             *         'SubmenuName',
+             *         array('module' => 'MyPlugin', 'action' => 'index'),
+             *         Piwik::isUserIsSuperUser(),
+             *         $order = 6
+             *     );
+             * }
+             * ```
+             */
             Piwik_PostEvent('Menu.Admin.addItems');
         }
         return parent::get();
diff --git a/core/Menu/Main.php b/core/Menu/Main.php
index 828f82517a..236379078f 100644
--- a/core/Menu/Main.php
+++ b/core/Menu/Main.php
@@ -59,6 +59,27 @@ class Main extends MenuAbstract
     {
         // We trigger the Event only once!
         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. 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.
+             *
+             * Example:
+             * ```
+             * public function addMenuItems()
+             * {
+             *     Piwik_AddMenu(
+             *         'CustomMenuName',
+             *         'CustomSubmenuName',
+             *         array('module' => 'MyPlugin', 'action' => 'index'),
+             *         Piwik::isUserIsSuperUser(),
+             *         $order = 6
+             *     );
+             * }
+             * ```
+             */
             Piwik_PostEvent('Menu.Reporting.addItems');
         }
         return parent::get();
diff --git a/core/Menu/Top.php b/core/Menu/Top.php
index 31c8fbb86a..98087916a4 100644
--- a/core/Menu/Top.php
+++ b/core/Menu/Top.php
@@ -59,6 +59,27 @@ class Top extends MenuAbstract
     public function get()
     {
         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.
+             *
+             * Example:
+             * ```
+             * public function addMenuItems()
+             * {
+             *     Piwik_AddTopMenu(
+             *         'TopMenuName',
+             *         array('module' => 'MyPlugin', 'action' => 'index'),
+             *         Piwik::isUserIsSuperUser(),
+             *         $order = 6
+             *     );
+             * }
+             * ```
+             */
             Piwik_PostEvent('Menu.Top.addItems');
         }
         return parent::get();