refs #4199 documented some more events

core/API/Proxy.php

@@ -180,7 +180,19 @@ public function call($className, $methodName, $parametersRequest)
             // allow plugins to manipulate the value
             $pluginName = $this->getModuleNameFromClassName($className);
 
+            /**
+             * Generic hook that plugins can use to modify any input to any API method. You could also use this to build
+             * an enhanced permission system. The event is triggered shortly before any API method is executed.
+             *
+             * The `$fnalParameters` contains all paramteres that will be passed to the actual API method.
+             */
             Piwik_PostEvent(sprintf('API.Request.dispatch', $pluginName, $methodName), array(&$finalParameters));
+
+            /**
+             * This event is similar to the `API.Request.dispatch` event. It distinguishes the possibility to subscribe
+             * only to a specific API method instead of all API methods. You can use it for example to modify any input
+             * parameters or to execute any other logic before the actual API method is called.
+             */
             Piwik_PostEvent(sprintf('API.%s.%s', $pluginName, $methodName), array(&$finalParameters));
 
             // call the method
@@ -193,7 +205,40 @@ public function call($className, $methodName, $parametersRequest)
                       'action'     => $methodName,
                       'parameters' => $finalParameters)
             );
+
+            /**
+             * This event is similar to the `API.Request.dispatch.end` event. It distinguishes the possibility to
+             * subscribe only to the end of a specific API method instead of all API methods. You can use it for example
+             * to modify the response. The passed parameters contains the returned value as well as some additional
+             * meta information:
+             *
+             * ```
+             * function (
+             *     &$returnedValue,
+             *     array('className'  => $className,
+             *           'module'     => $pluginName,
+             *           'action'     => $methodName,
+             *           'parameters' => $finalParameters)
+             * );
+             * ```
+             */
             Piwik_PostEvent(sprintf('API.%s.%s.end', $pluginName, $methodName), $endHookParams);
+
+            /**
+             * Generic hook that plugins can use to modify any output of any API method. The event is triggered after
+             * any API method is executed but before the result is send to the user. The parameters originally
+             * passed to the controller are available as well:
+             *
+             * ```
+             * function (
+             *     &$returnedValue,
+             *     array('className'  => $className,
+             *           'module'     => $pluginName,
+             *           'action'     => $methodName,
+             *           'parameters' => $finalParameters)
+             * );
+             * ```
+             */
             Piwik_PostEvent(sprintf('API.Request.dispatch.end', $pluginName, $methodName), $endHookParams);
 
             // Restore the request

core/API/Request.php

@@ -181,6 +181,12 @@ static public function reloadAuthUsingTokenAuth($request = null)
         // if a token_auth is specified in the API request, we load the right permissions
         $token_auth = Common::getRequestVar('token_auth', '', 'string', $request);
         if ($token_auth) {
+
+            /**
+             * This event will be triggered if the token_auth is found in the $request parameter. In this case the
+             * current session will be authenticated using this token_auth. It will overwrite the previous Auth object.
+             * @matt
+             */
             Piwik_PostEvent('API.Request.authenticate', array($token_auth));
             Access::getInstance()->reloadAccess();
             SettingsServer::raiseMemoryLimitIfNecessary();

core/ArchiveProcessor/Day.php

@@ -104,6 +104,21 @@ protected function convertMetricsIdToName($data)
 
     protected function compute()
     {
+        /**
+         * This event is triggered when the archiver wants to compute a new archive. Use this event to archive your
+         * custom report data if needed.
+         *
+         * Example:
+         * ```
+         * public function archiveDay(ArchiveProcessor\Day $archiveProcessor)
+         * {
+         *     $archiving = new Archiver($archiveProcessor);
+         *     if ($archiving->shouldArchive()) {
+         *         $archiving->archiveDay();
+         *     }
+         * }
+         * ```
+         */
         Piwik_PostEvent('ArchiveProcessor.Day.compute', array(&$this));
     }
 }

core/ArchiveProcessor/Period.php

@@ -186,6 +186,21 @@ protected function getRecordDataTableSum($name, $invalidSummedColumnNameToRename
 
     protected function compute()
     {
+        /**
+         * This event is triggered when the archiver wants to compute a new archive. Use this event to archive your
+         * custom report data if needed.
+         *
+         * Example:
+         * ```
+         * public function archiveDay(ArchiveProcessor\Day $archiveProcessor)
+         * {
+         *     $archiving = new Archiver($archiveProcessor);
+         *     if ($archiving->shouldArchive()) {
+         *         $archiving->archivePeriod();
+         *     }
+         * }
+         * ```
+         */
         Piwik_PostEvent('ArchiveProcessor.Period.compute', array(&$this));
     }
 

core/Db/Schema.php

@@ -131,6 +131,9 @@ public static function getSchemas($adapterName)
     private function loadSchema()
     {
         $schema = null;
+        /**
+         * @matt can be removed?
+         */
         Piwik_PostEvent('Schema.loadSchema', array(&$schema));
         if ($schema === null) {
             $config = Config::getInstance();

core/FrontController.php

@@ -128,7 +128,7 @@ public function dispatch($module = null, $action = null, $parameters = null)
          * called. You could also use this to build an enhanced permission system. The event is triggered before any
          * controller is called.
          *
-         * The `$params array contains the following properties: `array($module, $action, $parameters, $controller)`
+         * The `$params` array contains the following properties: `array($module, $action, $parameters, $controller)`
          */
         Piwik_PostEvent('Request.dispatch', $params);
 

core/Menu/Admin.php

@@ -39,6 +39,27 @@ static public function getInstance()
     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();

core/Menu/Main.php

@@ -59,6 +59,27 @@ public function get()
     {
         // 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();

core/Menu/Top.php

@@ -59,6 +59,27 @@ public function addHtml($menuName, $data, $displayedForCurrentUser, $order, $too
     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();