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

28 files changed, 600 insertions, 285 deletions

diff --git a/core/API/Proxy.php b/core/API/Proxy.php
index f843bdb5fc..0f880b6adb 100644
--- a/core/API/Proxy.php
+++ b/core/API/Proxy.php
@@ -151,7 +151,7 @@ class Proxy extends Singleton
             $this->registerClass($className);
 
             // instanciate the object
-            $object = call_user_func(array($className, "getInstance"));
+            $object = $className::getInstance();
 
             // check method exists
             $this->checkMethodExists($className, $methodName);
@@ -166,17 +166,30 @@ class Proxy extends Singleton
             $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.
+             * Triggered before an API request is dispatched.
+             * 
+             * This event can be used to modify the input that is passed to every API method or just
+             * one.
+             * 
+             * @param array &$finalParameters List of parameters that will be passed to the 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.
+             * This event exists for convenience and is triggered directly after the [API.Request.dispatch](#)
+             * event is triggered.
+             * 
+             * It can be used to modify the input that is passed to a single API method. This is also
+             * possible with the [API.Request.dispatch](#) event, however that event requires event handlers
+             * check if the plugin name and method name are correct before modifying the parameters.
+             * 
+             * **Example**
+             * 
+             *     Piwik::addAction('API.Actions.getPageUrls', function (&$parameters) {
+             *         // ...
+             *     });
+             * 
+             * @param array &$finalParameters List of parameters that will be passed to the API method.
              */
             Piwik::postEvent(sprintf('API.%s.%s', $pluginName, $methodName), array(&$finalParameters));
 
@@ -192,37 +205,47 @@ class Proxy extends Singleton
             );
 
             /**
-             * 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:
+             * This event exists for convenience and is triggered immediately before the
+             * [API.Request.dispatch.end](#) event.
+             * 
+             * It can be used to modify the output of a single API method. This is also possible with
+             * the [API.Request.dispatch.end](#) event, however that event requires event handlers
+             * check if the plugin name and method name are correct before modifying the output.
              *
-             * ```
-             * function (
-             *     &$returnedValue,
-             *     array('className'  => $className,
-             *           'module'     => $pluginName,
-             *           'action'     => $methodName,
-             *           'parameters' => $finalParameters)
-             * );
-             * ```
+             * @param mixed &$returnedValue The value returned from the API method. This will not be
+             *                              a rendered string, but an actual object. For example, it
+             *                              could be a [DataTable](#).
+             * @param array $extraInfo An array holding information regarding the API request. Will
+             *                         contain the following data:
+             * 
+             *                         - **className**: The name of the namespace-d class name of the
+             *                                          API instance that's being called.
+             *                         - **module**: The name of the plugin the API request was
+             *                                       dispatched to.
+             *                         - **action**: The name of the API method that was executed.
+             *                         - **parameters**: The array of parameters passed to the API
+             *                                           method.
              */
             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)
-             * );
-             * ```
+             * Triggered directly after an API request is dispatched.
+             * 
+             * This event can be used to modify the output of any API method.
+             * 
+             * @param mixed &$returnedValue The value returned from the API method. This will not be
+             *                              a rendered string, but an actual object. For example, it
+             *                              could be a [DataTable](#).
+             * @param array $extraInfo An array holding information regarding the API request. Will
+             *                         contain the following data:
+             * 
+             *                         - **className**: The name of the namespace-d class name of the
+             *                                          API instance that's being called.
+             *                         - **module**: The name of the plugin the API request was
+             *                                       dispatched to.
+             *                         - **action**: The name of the API method that was executed.
+             *                         - **parameters**: The array of parameters passed to the API
+             *                                           method.
              */
             Piwik::postEvent(sprintf('API.Request.dispatch.end', $pluginName, $methodName), $endHookParams);
 
diff --git a/core/API/Request.php b/core/API/Request.php
index 8d183f3834..5330c444d6 100644
--- a/core/API/Request.php
+++ b/core/API/Request.php
@@ -239,8 +239,14 @@ class Request
         if ($token_auth) {
 
             /**
-             * This event is triggered when authenticating the API call, only if the token_auth is found in the request.
-             * In this case the current session should authenticate using this token_auth.
+             * Triggered when authenticating an API request. Only triggered if the **token_auth**
+             * query parameter is found in the request.
+             * 
+             * Plugins that provide authentication capabilities should subscribe to this event
+             * and make sure the authentication object (the object returned by `Registry::get('auth')`)
+             * is setup to use `$token_auth` when its `authenticate()` method is executed.
+             * 
+             * @param string $token_auth The value of the **token_auth** query parameter.
              */
             Piwik::postEvent('API.Request.authenticate', array($token_auth));
             Access::getInstance()->reloadAccess();
diff --git a/core/ArchiveProcessor/Day.php b/core/ArchiveProcessor/Day.php
index 8b76871c75..a28bf567a4 100644
--- a/core/ArchiveProcessor/Day.php
+++ b/core/ArchiveProcessor/Day.php
@@ -110,19 +110,27 @@ class Day extends ArchiveProcessor
     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();
+         * Triggered when the archiving process is initiated for a day period.
+         * 
+         * Plugins that compute analytics data should subscribe to this event. The
+         * actual archiving logic, however, should not be in the event handler, but
+         * in a class that descends from [Archiver](#).
+         * 
+         * To learn more about single day archiving, see the [ArchiveProcessor\Day](#)
+         * class.
+         * 
+         * **Example**
+         * 
+         *     public function archivePeriod(ArchiveProcessor\Day $archiveProcessor)
+         *     {
+         *         $archiving = new MyArchiver($archiveProcessor);
+         *         if ($archiving->shouldArchive()) {
+         *             $archiving->archiveDay();
+         *         }
          *     }
-         * }
-         * ```
+         * 
+         * @param Piwik\ArchiveProcessor\Day $archiveProcessor
+         *                                       The ArchiveProcessor that triggered the event.
          */
         Piwik::postEvent('ArchiveProcessor.Day.compute', array(&$this));
     }
diff --git a/core/ArchiveProcessor/Period.php b/core/ArchiveProcessor/Period.php
index 9e079188f3..f91400c640 100644
--- a/core/ArchiveProcessor/Period.php
+++ b/core/ArchiveProcessor/Period.php
@@ -221,19 +221,27 @@ class Period extends ArchiveProcessor
     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();
+         * Triggered when the archiving process is initiated for a non-day period.
+         * 
+         * Plugins that compute analytics data should subscribe to this event. The
+         * actual archiving logic, however, should not be in the event handler, but
+         * in a class that descends from [Archiver](#).
+         * 
+         * To learn more about non-day period archiving, see the [ArchiveProcessor\Period](#)
+         * class.
+         * 
+         * **Example**
+         * 
+         *     public function archivePeriod(ArchiveProcessor\Period $archiveProcessor)
+         *     {
+         *         $archiving = new MyArchiver($archiveProcessor);
+         *         if ($archiving->shouldArchive()) {
+         *             $archiving->archivePeriod();
+         *         }
          *     }
-         * }
-         * ```
+         * 
+         * @param Piwik\ArchiveProcessor\Period $archiveProcessor
+         *                                          The ArchiveProcessor that triggered the event.
          */
         Piwik::postEvent('ArchiveProcessor.Period.compute', array(&$this));
     }
diff --git a/core/AssetManager.php b/core/AssetManager.php
index 18f9392db2..4c59cadb9f 100644
--- a/core/AssetManager.php
+++ b/core/AssetManager.php
@@ -158,9 +158,12 @@ class AssetManager
         $mergedContent = $less->compile($mergedContent);
 
         /**
-         * This event is triggered after the less stylesheets are compiled to CSS and after the CSS is minified and
-         * merged into one file but before the generated CSS is written to disk. It can be used to change the modify the
-         * stylesheets to your needs, like replacing image paths or adding further custom stylesheets.
+         * Triggered after all less stylesheets are compiled to CSS, minified and merged into
+         * one file, but before the generated CSS is written to disk.
+         * 
+         * This event can be used to modify merged CSS.
+         * 
+         * @param string &$mergedContent The merged an minified CSS.
          */
         Piwik::postEvent('AssetManager.filterMergedStylesheets', array(&$mergedContent));
 
@@ -283,19 +286,28 @@ class AssetManager
         $stylesheets = array();
 
         /**
-         * This event is triggered to gather a list of all stylesheets (CSS and LESS). Use this event to add your own
-         * stylesheets. Note: In case you are in development you may enable the config setting `disable_merged_assets`.
-         * Otherwise your custom stylesheets won't be loaded. It is best practice to place stylesheets within a
-         * `stylesheets` folder.
+         * Triggered when gathering the list of all stylesheets (CSS and LESS) needed by
+         * Piwik and its plugins.
+         * 
+         * Plugins that have stylesheets should use this event to make those stylesheets
+         * load.
+         * 
+         * Stylesheets should be placed within a **stylesheets** subfolder in your plugin's
+         * root directory.
+         * 
+         * Note: In case you are developing your plugin you may enable the config setting
+         * `[Debug] disable_merged_assets`. Otherwise your custom stylesheets won't be
+         * reloaded immediately after a change.
          *
-         * Example:
-         * ```
-         * public function getStylesheetFiles(&$stylesheets)
-         * {
-         *     $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.less";
-         *     $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.css";
-         * }
-         * ```
+         * **Example**
+         * 
+         *     public function getStylesheetFiles(&$stylesheets)
+         *     {
+         *         $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.less";
+         *         $stylesheets[] = "plugins/MyPlugin/stylesheets/myotherfile.css";
+         *     }
+         * 
+         * @param string[] &$stylesheets The list of stylesheet paths.
          */
         Piwik::postEvent(self::STYLESHEET_IMPORT_EVENT, array(&$stylesheets));
 
@@ -370,9 +382,13 @@ class AssetManager
         $mergedContent = str_replace("\n", "\r\n", $mergedContent);
 
         /**
-         * This event is triggered after the JavaScript files are minified and merged to a single file but before the
-         * generated JS file is written to disk. It can be used to change the generated JavaScript to your needs,
-         * like adding further scripts or storing the generated file somewhere else.
+         * Triggered after all JavaScript files Piwik uses are minified and merged into a
+         * single file, but before the merged JavaScript is written to disk.
+         * 
+         * Plugins can use this event to modify merged JavaScript or do something else
+         * with it.
+         * 
+         * @param string &$mergedContent The minified and merged JavaScript.
          */
         Piwik::postEvent('AssetManager.filterMergedJavaScripts', array(&$mergedContent));
 
@@ -406,19 +422,28 @@ class AssetManager
         $jsFiles = array();
 
         /**
-         * This event is triggered to gather a list of all JavaScript files. Use this event to add your own JavaScript
-         * files. Note: In case you are in development you may enable the config setting `disable_merged_assets`.
-         * Otherwise your custom JavaScript won't be loaded. It is best practice to place all your JavaScript files
-         * within a `javascripts` folder.
+         * Triggered when gathering the list of all JavaScript files needed by Piwik
+         * and its plugins.
+         * 
+         * Plugins that have their own JavaScript should use this event to make those
+         * files load in the browser.
+         * 
+         * JavaScript files should be placed within a **javascripts** subfolder in your
+         * plugin's root directory.
+         * 
+         * Note: In case you are developing your plugin you may enable the config setting
+         * `[Debug] disable_merged_assets`. Otherwise your JavaScript won't be reloaded
+         * immediately after a change.
          *
-         * Example:
-         * ```
-         * public function getJsFiles(&jsFiles)
-         * {
-         *     jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js";
-         *     jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js";
-         * }
-         * ```
+         * **Example**
+         * 
+         *     public function getJsFiles(&jsFiles)
+         *     {
+         *         jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js";
+         *         jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js";
+         *     }
+         * 
+         * @param string[] $jsFiles The JavaScript files to load.
          */
         Piwik::postEvent(self::JAVASCRIPT_IMPORT_EVENT, array(&$jsFiles));
         $jsFiles = self::sortJsFiles($jsFiles);
diff --git a/core/DataTable.php b/core/DataTable.php
index 158ca4dc9a..6fc0b61e54 100644
--- a/core/DataTable.php
+++ b/core/DataTable.php
@@ -99,7 +99,6 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
  * - **ArchiveProcessor** — to learn how DataTables are persisted.
  * - **DataTable\Renderer** — to learn how DataTable data is exported to XML, JSON, etc.
  * - **DataTable\Filter** — to see all core Filters.
- * - **DataTable\Manager** — to learn how DataTables are loaded.
  * 
  * ### Examples
  * 
@@ -1405,8 +1404,8 @@ class DataTable implements DataTableInterface
 
     /**
      * Traverses a DataTable tree using an array of labels and returns the row
-     * it finds or false if it cannot find one, and the number of segments of
-     * the path successfully walked.
+     * it finds or false if it cannot find one. The number of path segments that
+     * were successfully walked is also returned.
      * 
      * If $missingRowColumns is supplied, the specified path is created. When
      * a subtable is encountered w/o the queried label, a new row is created
diff --git a/core/Db.php b/core/Db.php
index 15613026f6..f2d56c7192 100644
--- a/core/Db.php
+++ b/core/Db.php
@@ -74,9 +74,21 @@ class Db
         }
 
         /**
-         * This event is triggered before a connection to the database is established. Use it to dynamically change the
-         * datatabase settings defined in the config. The reporting database config is used in case someone accesses
-         * the Piwik UI.
+         * Triggered before a connection to the database is established.
+         * 
+         * This event can be used to dynamically change the settings used to connect to the
+         * database.
+         * 
+         * @param array $dbInfos Reference to an array containing database connection info,
+         *                       including:
+         *                       - **host**: The host name or IP address to the MySQL database.
+         *                       - **username**: The username to use when connecting to the
+         *                                       database.
+         *                       - **password**: The password to use when connecting to the
+         *                                       database.
+         *                       - **dbname**: The name of the Piwik MySQL database.
+         *                       - **port**: The MySQL database port to use.
+         *                       - **adapter**: either `'PDO_MYSQL'` or `'MYSQLI'`
          */
         Piwik::postEvent('Reporting.getDatabaseConfig', array(&$dbInfos));
 
diff --git a/core/FrontController.php b/core/FrontController.php
index 2d4ae2d1c5..2cbc03c1af 100644
--- a/core/FrontController.php
+++ b/core/FrontController.php
@@ -49,7 +49,7 @@ use Piwik\Session;
  *         echo $realtimeMap->render();
  *     }
  *
- * For a detailed explanation, see the documentation on http://piwik.org/docs/plugins/framework-overview
+ * For a detailed explanation, see the documentation [here](http://piwik.org/docs/plugins/framework-overview).
  *
  * @package Piwik
  * @subpackage FrontController
@@ -88,35 +88,52 @@ class FrontController extends Singleton
         list($module, $action, $parameters, $controller) = $this->prepareDispatch($module, $action, $parameters);
 
         /**
-         * Generic hook that plugins can use to modify any input to the function, or even change the plugin being
-         * called. You could also use this to build an enhanced permission system. The event is triggered before every
-         * call to a controller method.
-         *
-         * The `$params` array contains the following properties: `array($module, $action, $parameters, $controller)`
+         * Triggered directly before controller actions are dispatched.
+         * 
+         * This event can be used to modify the parameters passed to one or more controller actions
+         * and can be used to change the plugin and action that is being dispatched to.
+         * 
+         * @param string &$module The name of the plugin being dispatched to.
+         * @param string &$action The name of the controller method being dispatched to.
+         * @param array &$parameters The arguments passed to the controller action.
          */
-        Piwik::postEvent('Request.dispatch', array($module, $action, $parameters));
+        Piwik::postEvent('Request.dispatch', array(&$module, &$action, &$parameters));
 
         /**
-         * This event is similar to the `Request.dispatch` hook. It distinguishes the possibility to subscribe only to a
-         * specific controller method instead of all controller methods. You can use it for example to modify any input
-         * parameters or execute any other logic before the actual controller is called.
+         * This event exists for convenience and is triggered directly after the [Request.dispatch](#)
+         * event is triggered.
+         * 
+         * It can be used to do the same things as the [Request.dispatch](#) event, but for one controller
+         * action only. Using this event will result in a little less code than [Request.dispatch](#).
+         * 
+         * @param array &$parameters The arguments passed to the controller action.
          */
-        Piwik::postEvent(sprintf('Controller.%s.%s', $module, $action), array($parameters));
+        Piwik::postEvent(sprintf('Controller.%s.%s', $module, $action), array(&$parameters));
 
         try {
             $result = call_user_func_array(array($controller, $action), $parameters);
 
             /**
-             * This event is similar to the `Request.dispatch.end` hook. It distinguishes the possibility to subscribe
-             * only to the end of a specific controller method instead of all controller methods. You can use it for
-             * example to modify the response of a single controller method.
+             * This event exists for convenience and is triggered immediately before the
+             * [Request.dispatch.end](#) event is triggered.
+             * 
+             * It can be used to do the same things as the [Request.dispatch.end](#) event, but for one
+             * controller action only. Using this event will result in a little less code than
+             * [Request.dispatch.end](#).
+             * 
+             * @param mixed &$result The result of the controller action.
+             * @param array $parameters The arguments passed to the controller action.
              */
             Piwik::postEvent(sprintf('Controller.%s.%s.end', $module, $action), array(&$result, $parameters));
 
             /**
-             * Generic hook that plugins can use to modify any output of any controller method. The event is triggered
-             * after a controller method is executed but before the result is send to the user. The parameters
-             * originally passed to the method are available as well.
+             * Triggered after a controller action is successfully called.
+             * 
+             * This event can be used to modify controller action output (if there was any) before
+             * the output is returned.
+             * 
+             * @param mixed &$result The result of the controller action.
+             * @param array $parameters The arguments passed to the controller action.
              */
             Piwik::postEvent('Request.dispatch.end', array(&$result, $parameters));
 
@@ -125,9 +142,12 @@ class FrontController extends Singleton
         } catch (NoAccessException $exception) {
 
             /**
-             * This event is triggered in case the user wants to access anything in the Piwik UI but has not the
-             * required permissions to do this. You can subscribe to this event to display a custom error message or
-             * to display a custom login form in such a case.
+             * Triggered when a user with insufficient access permissions tries to view some resource.
+             * 
+             * This event can be used to customize the error that occurs when a user is denied access
+             * (for example, displaying an error message, redirecting to a page other than login, etc.).
+             * 
+             * @param NoAccessException $exception The exception that was caught.
              */
             Piwik::postEvent('User.isNotAuthorized', array($exception), $pending = true);
         } catch (Exception $e) {
@@ -207,9 +227,11 @@ class FrontController extends Singleton
         } catch (Exception $exception) {
 
             /**
-             * This event is triggered in case no configuration file is available. This usually means Piwik is not
-             * installed yet. The event can be used to start the installation process or to display a custom error
-             * message.
+             * Triggered when the configuration file cannot be found or read. This usually
+             * means Piwik is not installed yet. This event can be used to start the
+             * installation process or to display a custom error message.
+             * 
+             * @param Exception $exception The exception that was thrown by `Config::getInstance()`.
              */
             Piwik::postEvent('Config.NoConfigurationFile', array($exception), $pending = true);
             $exceptionToThrow = $exception;
@@ -280,9 +302,12 @@ class FrontController extends Singleton
                 }
 
                 /**
-                 * This event is triggered in case a config file is not in the correct format or in case required values
-                 * are missing. The event can be used to start the installation process or to display a custom error
-                 * message.
+                 * Triggered if the INI config file has the incorrect format or if certain required configuration
+                 * options are absent. This event can be used to start the installation process or to display a
+                 * custom error message.
+                 * 
+                 * @param $exception Exception The exception thrown from creating and testing the database
+                 *                             connection.
                  */
                 Piwik::postEvent('Config.badConfigurationFile', array($exception), $pending = true);
                 throw $exception;
@@ -292,8 +317,9 @@ class FrontController extends Singleton
             Access::getInstance();
 
             /**
-             * This event is the first event triggered just after the platform is initialized and plugins are loaded.
-             * You can use this event to do early initialization. Note: the user is not authenticated yet.
+             * Triggered just after the platform is initialized and plugins are loaded.
+             * This event can be used to do early initialization. Note: At this point the user
+             * is not authenticated yet.
              */
             Piwik::postEvent('Request.dispatchCoreAndPluginUpdatesScreen');
 
@@ -305,8 +331,9 @@ class FrontController extends Singleton
             }
 
             /**
-             * This event is triggered before the user is authenticated. You can use it to create your own
-             * authentication object which implements the `Piwik\Auth` interface, and override the default authentication logic.
+             * Triggered before the user is authenticated. You can use it to create your own
+             * authentication object which implements the [Piwik\Auth](#) interface and overrides
+             * the default authentication logic.
              */
             Piwik::postEvent('Request.initAuthenticationObject');
             try {
@@ -330,9 +357,10 @@ class FrontController extends Singleton
             $pluginsManager->postLoadPlugins();
 
             /**
-             * This event is triggered to check for updates. It is triggered after the platform is initialized and after
-             * the user is authenticated but before the platform is going to dispatch the actual request. You can use
-             * it to check for any updates.
+             * Triggered after the platform is initialized and after the user has been authenticated, but
+             * before the platform dispatched the request.
+             * 
+             * Piwik uses this event to check for updates to Piwik.
              */
             Piwik::postEvent('Updater.checkForUpdates');
         } catch (Exception $e) {
@@ -472,4 +500,4 @@ class PluginDeactivatedException extends Exception
     {
         parent::__construct("The plugin $module is not enabled. You can activate the plugin on Settings > Plugins page in Piwik.");
     }
-}
+}
\ No newline at end of file
diff --git a/core/Log.php b/core/Log.php
index 40ac327f54..fce940a6fc 100644
--- a/core/Log.php
+++ b/core/Log.php
@@ -310,16 +310,17 @@ class Log extends Singleton
          *
          * Logging writers must be associated by name in the array passed to event handlers.
          *
-         * Example handler:
-         * ```
-         * function (&$writers) {
-         *     $writers['myloggername'] = function ($level, $tag, $datetime, $message) {
-         *         ...
+         * ***Example**
+         * 
+         *     function (&$writers) {
+         *         $writers['myloggername'] = function ($level, $tag, $datetime, $message) {
+         *             // ...
+         *         };
          *     }
-         * }
          *
-         * // 'myloggername' can now be used in the log_writers config option.
-         * ```
+         *     // 'myloggername' can now be used in the log_writers config option.
+         * 
+         * @param $
          */
         Piwik::postEvent(self::GET_AVAILABLE_WRITERS_EVENT, array(&$writers));
 
@@ -340,9 +341,14 @@ class Log extends Singleton
              * This event is called when trying to log an object to a file. Plugins can use
              * this event to convert objects to strings before they are logged.
              *
-             * The $message parameter is the object that is being logged. Event handlers should
-             * check if the object is of a certain type and if it is, set $message to the
-             * string that should be logged.
+             * @param mixed &$message The object that is being logged. Event handlers should
+             *                        check if the object is of a certain type and if it is,
+             *                        set $message to the string that should be logged.
+             * @param int $level The log level used with this log entry.
+             * @param string $tag The current plugin that started logging (or if no plugin,
+             *                    the current class).
+             * @param string $datetime Datetime of the logging call.
+             * @param Log $logger The Log singleton.
              */
             Piwik::postEvent(self::FORMAT_FILE_MESSAGE_EVENT, array(&$message, $level, $tag, $datetime, $logger));
         }
@@ -381,12 +387,17 @@ class Log extends Singleton
              * This event is called when trying to log an object to the screen. Plugins can use
              * this event to convert objects to strings before they are logged.
              *
-             * The $message parameter is the object that is being logged. Event handlers should
-             * check if the object is of a certain type and if it is, set $message to the
-             * string that should be logged.
-             *
              * The result of this callback can be HTML so no sanitization is done on the result.
              * This means YOU MUST SANITIZE THE MESSAGE YOURSELF if you use this event.
+             *
+             * @param mixed &$message The object that is being logged. Event handlers should
+             *                        check if the object is of a certain type and if it is,
+             *                        set $message to the string that should be logged.
+             * @param int $level The log level used with this log entry.
+             * @param string $tag The current plugin that started logging (or if no plugin,
+             *                    the current class).
+             * @param string $datetime Datetime of the logging call.
+             * @param Log $logger The Log singleton.
              */
             Piwik::postEvent(self::FORMAT_SCREEN_MESSAGE_EVENT, array(&$message, $level, $tag, $datetime, $logger));
         }
@@ -409,9 +420,14 @@ class Log extends Singleton
              * This event is called when trying to log an object to a database table. Plugins can use
              * this event to convert objects to strings before they are logged.
              *
-             * The $message parameter is the object that is being logged. Event handlers should
-             * check if the object is of a certain type and if it is, set $message to the
-             * string that should be logged.
+             * @param mixed &$message The object that is being logged. Event handlers should
+             *                        check if the object is of a certain type and if it is,
+             *                        set $message to the string that should be logged.
+             * @param int $level The log level used with this log entry.
+             * @param string $tag The current plugin that started logging (or if no plugin,
+             *                    the current class).
+             * @param string $datetime Datetime of the logging call.
+             * @param Log $logger The Log singleton.
              */
             Piwik::postEvent(self::FORMAT_DATABASE_MESSAGE_EVENT, array(&$message, $level, $tag, $datetime, $logger));
         }
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');
         }
diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php
index 82444bcd7f..49ef36c6e8 100644
--- a/core/Plugin/ViewDataTable.php
+++ b/core/Plugin/ViewDataTable.php
@@ -102,19 +102,25 @@ abstract class ViewDataTable implements ViewInterface
         $this->requestConfig->apiMethodToRequestDataTable = $apiMethodToRequestDataTable;
 
         /**
-         * This event is triggered to gather the report display properties for each available report. If you define
-         * your own report, you want to subscribe to this event to define how your report shall be displayed in the
-         * Piwik UI.
+         * Triggered during [ViewDataTable](#) is constructed. Subscribers should customize
+         * the view based on the report that it is displaying.
+         * 
+         * Plugins that define their own reports must subscribe to this event in order to
+         * customize how the Piwik UI will display and navigate the report.
+         * 
+         * **Example**
          *
-         * public function configureViewDataTable(ViewDataTable $view)
-         * {
-         *     switch ($view->requestConfig->apiMethodToRequestDataTable) {
-         *         case 'VisitTime.getVisitInformationPerServerTime':
-         *             $view->config->enable_sort = true;
-         *             $view->requestConfig->filter_limit = 10;
-         *             break;
+         *     public function configureViewDataTable(ViewDataTable $view)
+         *     {
+         *         switch ($view->requestConfig->apiMethodToRequestDataTable) {
+         *             case 'VisitTime.getVisitInformationPerServerTime':
+         *                 $view->config->enable_sort = true;
+         *                 $view->requestConfig->filter_limit = 10;
+         *                 break;
+         *         }
          *     }
-         * }
+         * 
+         * @param ViewDataTable $view The instance to configure.
          */
         Piwik::postEvent('ViewDataTable.configure', array($this));
 
diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php
index 27a99060ed..9b55655f43 100644
--- a/core/SettingsPiwik.php
+++ b/core/SettingsPiwik.php
@@ -63,9 +63,25 @@ class SettingsPiwik
             $segmentsToProcess = isset($segments['Segments']) ? $segments['Segments'] : array();
 
             /**
-             * This event is triggered when the automatic archiving runs.
-             * You can use it to add Segments to the list of segments to pre-process during archiving.
-             * Segments specified in this array will be pre-processed for all websites.
+             * Triggered during the cron archiving process to collect segments that
+             * should be pre-processed for all websites. The archiving process will be launched
+             * for each of these segments when archiving data for each site.
+             * 
+             * This event can be used to add segments to be pre-processed. This can be provide
+             * enhanced performance if your plugin depends on data from a specific segment.
+             * 
+             * Note: If you just want to add a segment that is managed by the user, you should use the
+             * SegmentEditor API.
+             * 
+             * @param array &$segmentsToProcess List of segment definitions, eg,
+             *                                  ```
+             *                                  array(
+             *                                      'browserCode=ff;resolution=800x600',
+             *                                      'country=JP;city=Tokyo'
+             *                                  )
+             *                                  ```
+             *                                  Add segments to process to this array in your event
+             *                                  handler.
              */
             Piwik::postEvent('Segments.getKnownSegmentsToArchiveAllSites', array(&$segmentsToProcess));
 
@@ -87,9 +103,26 @@ class SettingsPiwik
         $segments = array();
 
         /**
-         * This event is triggered when the automatic archiving runs.
-         * You can use it to add Segments to the list of segments to pre-process during archiving,
-         * for this particular website ID $idSite.
+         * Triggered during the cron archiving process to collect segments that
+         * should be pre-processed for one specific site. The archiving process will be launched
+         * for each of these segments when archiving data for that one site.
+         * 
+         * This event can be used to add segments to be pre-processed. This can be provide
+         * enhanced performance if your plugin depends on data from a specific segment.
+         * 
+         * Note: If you just want to add a segment that is managed by the user, you should use the
+         * SegmentEditor API.
+         * 
+         * @param array &$segmentsToProcess List of segment definitions, eg,
+         *                                  ```
+         *                                  array(
+         *                                      'browserCode=ff;resolution=800x600',
+         *                                      'country=JP;city=Tokyo'
+         *                                  )
+         *                                  ```
+         *                                  Add segments to process to this array in your event
+         *                                  handler.
+         * @param int $idSite The ID of the site to get segments for.
          */
         Piwik::postEvent('Segments.getKnownSegmentsToArchiveForSite', array(&$segments, $idSite));
         return $segments;
diff --git a/core/TaskScheduler.php b/core/TaskScheduler.php
index 6b4b13097f..4ab6d0122a 100644
--- a/core/TaskScheduler.php
+++ b/core/TaskScheduler.php
@@ -55,11 +55,14 @@ class TaskScheduler
         $tasks = array();
 
         /**
-         * This event can be used to register any tasks that you may want to schedule on a regular basis. For instance
-         * hourly, daily, weekly or monthly. It is comparable to a cronjob. The registered method will be executed
-         * depending on the interval that you specify. See `Piwik\ScheduledTask` for more information.
+         * Triggered when the TaskScheduler runs scheduled tasks. Collects all the tasks that
+         * will be run.
+         * 
+         * Subscribe to this event to schedule code execution on an hourly, daily, weekly or monthly
+         * basis.
          *
-         * Example:
+         * **Example**
+         * 
          * ```
          * public function getScheduledTasks(&$tasks)
          * {
@@ -72,6 +75,8 @@ class TaskScheduler
          *     );
          * }
          * ```
+         * 
+         * @param ScheduledTask[] &$tasks List of tasks to run periodically.
          */
         Piwik::postEvent(self::GET_TASKS_EVENT, array(&$tasks));
         /** @var ScheduledTask[] $tasks */
diff --git a/core/Tracker.php b/core/Tracker.php
index f4618ee3b3..da0a712570 100644
--- a/core/Tracker.php
+++ b/core/Tracker.php
@@ -557,9 +557,21 @@ class Tracker
         }
 
         /**
-         * This event is triggered before a connection to the database is established. Use it to dynamically change the
-         * datatabase settings defined in the config. The tracker database config is used in case a new pageview/visit
-         * will be tracked.
+         * Triggered before a connection to the database is established in the Tracker.
+         * 
+         * This event can be used to dynamically change the settings used to connect to the
+         * database.
+         * 
+         * @param array $dbInfos Reference to an array containing database connection info,
+         *                       including:
+         *                       - **host**: The host name or IP address to the MySQL database.
+         *                       - **username**: The username to use when connecting to the
+         *                                       database.
+         *                       - **password**: The password to use when connecting to the
+         *                                       database.
+         *                       - **dbname**: The name of the Piwik MySQL database.
+         *                       - **port**: The MySQL database port to use.
+         *                       - **adapter**: either `'PDO_MYSQL'` or `'MYSQLI'`
          */
         Piwik::postEvent('Tracker.getDatabaseConfig', array(&$configDb));
 
@@ -610,9 +622,13 @@ class Tracker
         $visit = null;
 
         /**
-         * This event is triggered once a new `Piwik\Tracker\Visit` object is requested. Use this event to force the
-         * usage of your own or your extended visit object but make sure to implement the
-         * `Piwik\Tracker\VisitInterface`.
+         * Triggered before a new `Piwik\Tracker\Visit` object is created. Subscribers to this
+         * event can force the use of a custom visit object that extends from
+         * [Piwik\Tracker\VisitInterface](#).
+         * 
+         * @param Piwik\Tracker\VisitInterface &$visit Initialized to null, but can be set to
+         *                                             a created Visit object. If it isn't
+         *                                             modified Piwik uses the default class.
          */
         Piwik::postEvent('Tracker.makeNewVisitObject', array(&$visit));
 
diff --git a/core/Tracker/Action.php b/core/Tracker/Action.php
index 6a47669b76..75f7584196 100644
--- a/core/Tracker/Action.php
+++ b/core/Tracker/Action.php
@@ -642,8 +642,22 @@ class Action implements ActionInterface
         Common::printDebug($insertWithoutNulls);
 
         /**
-         * This hook is called after saving (and updating) visitor information. You can use it for instance to sync the
-         * recorded action with third party systems.
+         * Triggered after successfully logging an action for a visit.
+         * 
+         * 
+         * @param Action $trackerAction The Action tracker instance.
+         * @param array $info An array describing the current visit action. Includes the
+         *                    following information:
+         *                    - **idSite**: The ID of the site that we are tracking.
+         *                    - **idLinkVisitAction**: The ID of the row that was inserted into the
+         *                                             log_link_visit_action table.
+         *                    - **idVisit**: The visit ID.
+         *                    - **idReferrerActionUrl**: The ID referencing the row in the log_action table
+         *                                               that holds the URL of the visitor's last action.
+         *                    - **idReferrerActionName**: The ID referencing the row in the log_action table
+         *                                                that holds the name of the visitor's last action.
+         *                    - **timeSpentReferrerAction**: The number of seconds since the visitor's last
+         *                                                   action.
          */
         Piwik::postEvent('Tracker.recordAction', array($trackerAction = $this, $info));
     }
diff --git a/core/Tracker/Cache.php b/core/Tracker/Cache.php
index ae328aed38..bd03bdb1f0 100644
--- a/core/Tracker/Cache.php
+++ b/core/Tracker/Cache.php
@@ -62,9 +62,21 @@ class Cache
         Piwik::setUserIsSuperUser();
 
         $content = array();
+        
         /**
-         * This hook is called to get the details of a specific site depending on the id. You can use this to add any
-         * custom attributes to the website.
+         * This event is called to get the details of a site by its ID. It can be used to
+         * add custom attributes for the website to the Tracker cache.
+         * 
+         * **Example**
+         * 
+         *     public function getSiteAttributes($content, $idSite)
+         *     {
+         *         $sql = "SELECT info FROM " . Common::prefixTable('myplugin_extra_site_info') . " WHERE idsite = ?";
+         *         $content['myplugin_site_data'] = Db::fetchOne($sql, array($idSite));
+         *     }
+         * 
+         * @param array &$content List of attributes.
+         * @param int $idSite The site ID.
          */
         Piwik::postEvent('Site.getSiteAttributes', array(&$content, $idSite));
 
@@ -111,8 +123,23 @@ class Cache
         );
 
         /**
-         * This event is triggered to add any custom content to the Tracker cache. You may want to cache any tracker
-         * data that is expensive to re-calculate on each tracking request.
+         * Triggered before the general tracker cache is saved to disk. This event can be
+         * used to add extra content to the cace.
+         * 
+         * Data that is used during tracking but is expensive to compute/query should be
+         * cached so as not to slow the tracker down. One example of such data are options
+         * that are stored in the piwik_option table. Requesting data on each tracking
+         * request means an extra unnecessary database query on each visitor action.
+         * 
+         * **Example**
+         * 
+         *     public function setTrackerCacheGeneral(&$cacheContent)
+         *     {
+         *         $cacheContent['MyPlugin.myCacheKey'] = Option::get('MyPlugin_myOption');
+         *     }
+         * 
+         * @param array &$cacheContent Array of cached data. Each piece of data must be
+         *                             mapped by name.
          */
         Piwik::postEvent('Tracker.setTrackerCacheGeneral', array(&$cacheContent));
         self::setCacheGeneral($cacheContent);
diff --git a/core/Tracker/GoalManager.php b/core/Tracker/GoalManager.php
index 3e3fcf874e..efc60705c8 100644
--- a/core/Tracker/GoalManager.php
+++ b/core/Tracker/GoalManager.php
@@ -407,10 +407,14 @@ class GoalManager
         }
 
         /**
-         * This hook is called after recording an ecommerce goal. You can use it for instance to sync the recorded goal
-         * with third party systems. `$goal` contains all available information like `items` and `revenue`.
+         * Triggered after successfully recording an ecommerce goal conversion.
+         * 
+         * TODO: figure out what exactly is in $goal and $items
+         * 
+         * @param array $goal Contains conversion information.
+         * @param array $items List of arrays containing information for each ecommerce item.
          */
-        Piwik::postEvent('Tracker.recordEcommerceGoal', array($goal));
+        Piwik::postEvent('Tracker.recordEcommerceGoal', array($goal, $items));
     }
 
     /**
@@ -772,8 +776,12 @@ class GoalManager
             $this->recordGoal($newGoal);
 
             /**
-             * This hook is called after recording a standard goal. You can use it for instance to sync the recorded
-             * goal with third party systems. `$goal` contains all available information like `url` and `revenue`.
+             * Triggered after successfully recording a standard goal (meaning non-ecommerce related)
+             * conversion.
+             * 
+             * TODO: list what information is in $newGoal
+             * 
+             * @param array $newGoal Contains information about the goal.
              */
             Piwik::postEvent('Tracker.recordStandardGoals', array($newGoal));
         }
@@ -841,4 +849,4 @@ class GoalManager
             (string)$row[self::INTERNAL_ITEM_QUANTITY],
         );
     }
-}
+}
\ No newline at end of file
diff --git a/core/Tracker/Referrer.php b/core/Tracker/Referrer.php
index 09501943ce..4563d9e92e 100644
--- a/core/Tracker/Referrer.php
+++ b/core/Tracker/Referrer.php
@@ -130,8 +130,20 @@ class Referrer
         $searchEngineInformation = UrlHelper::extractSearchEngineInformationFromUrl($this->referrerUrl);
 
         /**
-         * This event is triggered after basic search engine detection has been attempted. A plugin can use this event
-         * to modify or provide new results based on the passed referrer URL.
+         * Triggered when detecting the search engine of a referrer URL.
+         * 
+         * Plugins can use this event to provide custom search engine detection
+         * logic.
+         * 
+         * @param array &$searchEngineInformation An array with the following information:
+         * 
+         *                                        - **name**: The search engine name.
+         *                                        - **keywords**: The search keywords used.
+         *  
+         *                                        This parameter will be defaulted to the results
+         *                                        of Piwik's default search engine detection
+         *                                        logic.
+         * @param string referrerUrl The referrer URL.
          */
         Piwik::postEvent('Tracker.detectReferrerSearchEngine', array(&$searchEngineInformation, $this->referrerUrl));
         if ($searchEngineInformation === false) {
diff --git a/core/Tracker/Request.php b/core/Tracker/Request.php
index 013bcb18da..84e60fd85c 100644
--- a/core/Tracker/Request.php
+++ b/core/Tracker/Request.php
@@ -17,8 +17,8 @@ use Piwik\Tracker;
  *
  * @category Piwik
  * @package Piwik
+ * @api
  */
-
 class Request
 {
     /**
@@ -294,13 +294,20 @@ class Request
         $idSite = Common::getRequestVar('idsite', 0, 'int', $this->params);
 
         /**
-         * This event allows a plugin to set/change the idsite in the tracking request. Note: A modified idSite has to
-         * be higher than `0`, otherwise an exception will be triggered. By default the idSite is specified on the URL
-         * parameter `idsite`.
+         * Triggered when obtaining the ID of the site that is currently being tracked.
+         * 
+         * This event can be used to modify the site ID from what is specified by the **idsite**
+         * query parameter.
+         * 
+         * @param int &$idSite Initialized to the value of the **idsite** query parameter. If a
+         *                     subscriber sets this variable, the value it uses must be greater
+         *                     than 0.
+         * @param array $params The entire array of request parameters passed with this tracking
+         *                      request.
          */
         Piwik::postEvent('Tracker.Request.getIdSite', array(&$idSite, $this->params));
         if ($idSite <= 0) {
-            throw new Exception('Invalid idSite');
+            throw new Exception('Invalid idSite: \'' . $idSite . '\'');
         }
         return $idSite;
     }
@@ -541,6 +548,4 @@ class Request
         }
         return false;
     }
-
-
-}
+}
\ No newline at end of file
diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php
index d1290f3d1d..27127fd9a6 100644
--- a/core/Tracker/Visit.php
+++ b/core/Tracker/Visit.php
@@ -93,7 +93,12 @@ class Visit implements VisitInterface
         }
 
         /**
-         * This event can be used for instance to anonymize the IP (after testing for IP exclusion).
+         * Triggered after the IP address of the visitor is determined.
+         * 
+         * Event subscribers can modify the IP address before it is persisted, for example,
+         * to anonymize it.
+         * 
+         * @param string $ip
          */
         Piwik::postEvent('Tracker.setVisitorIp', array(&$this->visitorInfo['location_ip']));
 
@@ -306,8 +311,13 @@ class Visit implements VisitInterface
         $valuesToUpdate = array_merge($valuesToUpdate, $this->visitorCustomVariables);
 
         /**
-         * This event is triggered before saving a known visitor. Use it to change any visitor information before
-         * the visitor is saved.
+         * Triggered before logging the visit from a known visitor.
+         * 
+         * Event subscribers may modify the visitor information before it is saved.
+         * 
+         * TODO: describe exactly what information can be added to $visitInfo
+         * 
+         * @param array $visitInfo The array of visit information.
          */
         Piwik::postEvent('Tracker.knownVisitorUpdate', array(&$valuesToUpdate));
 
@@ -351,8 +361,11 @@ class Visit implements VisitInterface
         }
 
         /**
-         * After a known visitor is saved and updated by Piwik, this event is called. Useful for plugins that want to
-         * register information about a returning visitor, or filter the existing information.
+         * Triggered after a visit from a known visitor is successfully logged.
+         * 
+         * TODO: Describe what information is available in $visit
+         * 
+         * @param array $visit Information about the visit.
          */
         Piwik::postEvent('Tracker.knownVisitorInformation', array(&$this->visitorInfo));
     }
@@ -472,9 +485,21 @@ class Visit implements VisitInterface
         );
 
         /**
-         * Before a new visitor is saved by Piwik, this event is called. Useful for plugins that want to register
-         * new information about a visitor, or filter the existing information. `$extraInfo` contains the UserAgent.
-         * You can for instance change the user's location country depending on the User Agent.
+         * Triggered before a visit from a new visitor is logged.
+         * 
+         * This event can be used to determine and set new visit information before the visit is
+         * logged. The UserCountry plugin, for example, uses this event to inject location information
+         * into the visit log table.
+         * 
+         * TODO: list exactly what information is available in $visitInfo
+         * 
+         * @param array $visitInfo Information regarding the visit. This is information that
+         *                         persisted to the database.
+         * @param array $extraInfo Extra information about the visit. This information will not
+         *                         be persisted. Includes the following data:
+         * 
+         *                         - **UserAgent**: The whole User-Agent of the tracking request (or
+         *                                          the value of the **ua** query parameter).
          */
         Piwik::postEvent('Tracker.newVisitorInformation', array(&$this->visitorInfo, $extraInfo));
 
diff --git a/core/Tracker/VisitExcluded.php b/core/Tracker/VisitExcluded.php
index 48d37036c6..b9506bc46d 100644
--- a/core/Tracker/VisitExcluded.php
+++ b/core/Tracker/VisitExcluded.php
@@ -73,8 +73,13 @@ class VisitExcluded
         }
 
         /**
-         * At every page view, this event will be called. It is useful for plugins that want to exclude specific visits
-         * (ie. IP excluding, Cookie excluding). If you set `$excluded` to `true`, the visit will be excluded.
+         * Triggered on every pageview of a visitor.
+         * 
+         * This event can be used to tell the Tracker not to record this particular pageview.
+         * 
+         * @param bool &$excluded Whether the pageview should be excluded or not. Initialized
+         *                        to `false`. Event subscribers should set it to `true` in
+         *                        order to exclude the pageview.
          */
         Piwik::postEvent('Tracker.isExcludedVisit', array(&$excluded));
 
diff --git a/core/Tracker/VisitInterface.php b/core/Tracker/VisitInterface.php
index 87b3afc899..f736a0c663 100644
--- a/core/Tracker/VisitInterface.php
+++ b/core/Tracker/VisitInterface.php
@@ -14,6 +14,7 @@ namespace Piwik\Tracker;
 /**
  * @package Piwik
  * @subpackage Tracker
+ * @api
  */
 interface VisitInterface
 {
@@ -27,4 +28,4 @@ interface VisitInterface
      * @return void
      */
     public function handle();
-}
+}
\ No newline at end of file
diff --git a/core/Translate.php b/core/Translate.php
index f7e9808ad8..7b1dfb1e47 100644
--- a/core/Translate.php
+++ b/core/Translate.php
@@ -101,9 +101,25 @@ class Translate
             $lang = Common::getRequestVar('language', '', 'string');
 
             /**
-             * This event is triggered to identify the language code, such as 'en', for the current user. You can use
-             * it for instance to detect the users language by using a third party API such as a CMS. The language that
-             * is set in the request URL is passed as an argument.
+             * Triggered when the current user's language is requested.
+             * 
+             * By default the current language is determined by the **language** query
+             * parameter. Plugins can override this logic by subscribing to this event.
+             * 
+             * **Example**
+             * 
+             *     public function getLanguage(&$lang)
+             *     {
+             *         $client = new My3rdPartyAPIClient();
+             *         $thirdPartyLang = $client->getLanguageForUser(Piwik::getCurrentUserLogin());
+             * 
+             *         if (!empty($thirdPartyLang)) {
+             *             $lang = $thirdPartyLang;
+             *         }
+             *     }
+             * 
+             * @param string &$lang The language that should be used for the user. Will be
+             *                      initialized to the value of the **language** query parameter.
              */
             Piwik::postEvent('User.getLanguage', array(&$lang));
 
@@ -160,19 +176,20 @@ class Translate
         $result = array();
 
         /**
-         * This event is called before generating the JavaScript code that allows other JavaScript
-         * to access Piwik i18n strings. Plugins should handle this event to specify which translations
-         * should be available to JavaScript code.
+         * Triggered before generating the JavaScript code that allows i18n strings to be used
+         * in the browser. Plugins should subscribe to this event to specify which translations
+         * should be available in JavaScript code.
          *
          * Event handlers should add whole translation keys, ie, keys that include the plugin name.
-         * For example:
+         * 
+         * **Example**
          *
-         * ```
-         * public function getClientSideTranslationKeys(&$result)
-         * {
-         *     $result[] = "MyPlugin_MyTranslation";
-         * }
-         * ```
+         *     public function getClientSideTranslationKeys(&$result)
+         *     {
+         *         $result[] = "MyPlugin_MyTranslation";
+         *     }
+         * 
+         * @param array &$result The whole list of client side translation keys.
          */
         Piwik::postEvent('Translate.getClientSideTranslationKeys', array(&$result));
 
diff --git a/core/ViewDataTable/Factory.php b/core/ViewDataTable/Factory.php
index b4563b0607..44b047c671 100644
--- a/core/ViewDataTable/Factory.php
+++ b/core/ViewDataTable/Factory.php
@@ -11,7 +11,6 @@
 namespace Piwik\ViewDataTable;
 
 use Piwik\API\Proxy;
-use Piwik\API\Request;
 use Piwik\Common;
 use Piwik\Piwik;
 use Piwik\Plugins\API\API;
@@ -139,20 +138,20 @@ class Factory
         if (null === self::$defaultViewTypes) {
             self::$defaultViewTypes = array();
             /**
-             * This event is triggered to gather the default view types for each available report. By default a table
-             * is used. If you define your own report, you may want to subscribe to this event to define another
-             * Visualization that should be used by default to display your report. For instance a Pie, a Bar or a
-             * Cloud.
+             * Triggered when gathering the default view types for all available reports. By default the HtmlTable
+             * visualization is used. If you define your own report, you may want to subscribe to this event to
+             * make sure another Visualization is used (for example, a pie graph, bar graph, or something else).
              *
-             * Example:
+             * **Example**
              * ```
              * public function getDefaultTypeViewDataTable(&$defaultViewTypes)
              * {
              *     $defaultViewTypes['Referrers.getSocials']       = HtmlTable::ID;
              *     $defaultViewTypes['Referrers.getUrlsForSocial'] = Pie::ID;
-             *     )
              * }
              * ```
+             * 
+             * @param array &$defaultViewTypes The array mapping report IDs with visualization IDs.
              */
             Piwik::postEvent('ViewDataTable.getDefaultType', array(&self::$defaultViewTypes));
         }
diff --git a/core/ViewDataTable/Manager.php b/core/ViewDataTable/Manager.php
index 48d77eec14..3fbb2ca139 100644
--- a/core/ViewDataTable/Manager.php
+++ b/core/ViewDataTable/Manager.php
@@ -69,8 +69,19 @@ class Manager
         $visualizations = array();
 
         /**
-         * This event is used to gather all available DataTable visualizations. Callbacks should add visualization
-         * class names to the incoming array.
+         * Triggered when gathering all available DataTable visualizations.
+         * 
+         * Plugins that want to expose new DataTable visualizations should subscribe to
+         * this event and add visualization class names to the incoming array.
+         * 
+         * **Example**
+         * 
+         *     public function addViewDataTable(&$visualizations)
+         *     {
+         *         $visualizations[] = 'Piwik\\Plugins\\MyPlugin\\MyVisualization';
+         *     }
+         * 
+         * @param array &$visualizations The array of all available visualizations.
          */
         Piwik::postEvent('ViewDataTable.addViewDataTable', array(&$visualizations));
 
diff --git a/core/WidgetsList.php b/core/WidgetsList.php
index 08dae47210..91f753b389 100644
--- a/core/WidgetsList.php
+++ b/core/WidgetsList.php
@@ -74,11 +74,14 @@ class WidgetsList
             self::$hookCalled = true;
 
             /**
-             * This event is triggered to collect all available widgets. Subscribe to this event if you want to create
-             * one or more custom widgets. Just define the name of your widgets as well as a controller and an action
-             * that should be executed once your widget is requested.
+             * Triggered once when the widget list is first requested. Collects all available widgets.
+             * 
+             * Subscribe to this event to make your plugin's reports or other controller actions available
+             * as dashboard widgets. Event handlers should call the WidgetsList::add method for each
+             * new dashboard widget.
              *
-             * Example:
+             * **Example**
+             * 
              * ```
              * public function addWidgets()
              * {