refs #4199 documented some more events

7 files changed, 80 insertions, 1 deletions

diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php
index 5b82796df1..d4ef3d788e 100644
--- a/core/SettingsPiwik.php
+++ b/core/SettingsPiwik.php
@@ -62,6 +62,9 @@ class SettingsPiwik
             $segments = Config::getInstance()->Segments;
             $cachedResult = isset($segments['Segments']) ? $segments['Segments'] : array();
 
+            /**
+             * @matt
+             */
             Piwik_PostEvent('Segments.getKnownSegmentsToArchiveAllSites', array(&$cachedResult));
 
             self::$cachedKnownSegmentsToArchive = array_unique($cachedResult);
@@ -74,6 +77,10 @@ class SettingsPiwik
     public static function getKnownSegmentsToArchiveForSite($idSite)
     {
         $segments = array();
+
+        /**
+         * @matt
+         */
         Piwik_PostEvent('Segments.getKnownSegmentsToArchiveForSite', array(&$segments, $idSite));
         return $segments;
     }
diff --git a/core/TaskScheduler.php b/core/TaskScheduler.php
index 8bc1a7b3c7..865dc8a1a6 100644
--- a/core/TaskScheduler.php
+++ b/core/TaskScheduler.php
@@ -47,6 +47,26 @@ class TaskScheduler
 
         // collect tasks
         $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.
+         *
+         * Example:
+         * ``
+         * public function getScheduledTasks(&$tasks)
+         * {
+         *     $tasks[] = new ScheduledTask(
+         *         'Piwik\Plugins\CorePluginsAdmin\MarketplaceApiClient',
+         *         'clearAllCacheEntries',
+         *         null,
+         *         new Daily(),
+         *         ScheduledTask::LOWEST_PRIORITY
+         *     );
+         * }
+         * ```
+         */
         Piwik_PostEvent(self::GET_TASKS_EVENT, array(&$tasks));
         /** @var ScheduledTask[] $tasks */
 
diff --git a/core/Tracker.php b/core/Tracker.php
index 3a4c6bd113..333aff4d7b 100644
--- a/core/Tracker.php
+++ b/core/Tracker.php
@@ -554,6 +554,11 @@ class Tracker
             $configDb['port'] = '3306';
         }
 
+        /**
+         * 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.
+         */
         Piwik_PostEvent('Tracker.getDatabaseConfig', array(&$configDb));
 
         $db = Tracker::factory($configDb);
@@ -570,6 +575,12 @@ class Tracker
 
         try {
             $db = null;
+
+            /**
+             * This event is triggered after the database config is loaded but immediately before a connection to the
+             * database is established. Use this event to create your own database handler instead of the default Piwik
+             * DB handler.
+             */
             Piwik_PostEvent('Tracker.createDatabase', array(&$db));
             if (is_null($db)) {
                 $db = self::connectPiwikTrackerDb();
@@ -606,6 +617,12 @@ class Tracker
     protected function getNewVisitObject()
     {
         $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`.
+         */
         Piwik_PostEvent('Tracker.getNewVisitObject', array(&$visit));
 
         if (is_null($visit)) {
diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php
index 7df96eb24a..9a28dcb144 100644
--- a/core/Tracker/Visit.php
+++ b/core/Tracker/Visit.php
@@ -37,6 +37,7 @@ use UserAgentParser;
  *
  * @package Piwik
  * @subpackage Tracker
+ * @api
  */
 class Visit implements VisitInterface
 {
diff --git a/core/Translate.php b/core/Translate.php
index c8ce14789e..98e80139be 100644
--- a/core/Translate.php
+++ b/core/Translate.php
@@ -113,6 +113,11 @@ class Translate
         if (is_null(self::$languageToLoad)) {
             $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.
+             */
             Piwik_PostEvent('User.getLanguage', array(&$lang));
 
             self::$languageToLoad = $lang;
diff --git a/core/ViewDataTable.php b/core/ViewDataTable.php
index 6e24932914..8317c94e22 100644
--- a/core/ViewDataTable.php
+++ b/core/ViewDataTable.php
@@ -425,6 +425,22 @@ class ViewDataTable
     {
         if (self::$reportPropertiesCache === null) {
             self::$reportPropertiesCache = array();
+            /**
+             * This event is triggered to gather the report display properties for each available report. If you define
+             * your own report, you mant to subscribe to this event to define how your report shall be displayed in the
+             * Piwik UI.
+             *
+             * Example:
+             * ```
+             * public function getReportDisplayProperties(&$properties)
+             * {
+             *     $properties['Provider.getProvider'] = array(
+             *         'translations' => array('label' => Piwik_Translate('Provider_ColumnProvider')),
+             *         'filter_limit' => 5
+             *     )
+             * }
+             * ```
+             */
             Piwik_PostEvent('Visualization.getReportDisplayProperties', array(&self::$reportPropertiesCache));
         }
 
diff --git a/core/WidgetsList.php b/core/WidgetsList.php
index 01ac7f5178..40c531721c 100644
--- a/core/WidgetsList.php
+++ b/core/WidgetsList.php
@@ -38,7 +38,6 @@ class WidgetsList
     static public function get()
     {
         self::addWidgets();
-        Piwik_PostEvent('WidgetsList.getWidgets');
 
         uksort(self::$widgets, array('Piwik\WidgetsList', '_sortWidgetCategories'));
 
@@ -56,6 +55,20 @@ class WidgetsList
     {
         if (!self::$hookCalled) {
             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. It's fairly easy. Just define the name of your widgets as well as a
+             * controller and an action that should be executed once your widget is requested.
+             *
+             * Example:
+             * ```
+             * public function addWidgets()
+             * {
+             *     WidgetsList::add('General_Actions', 'General_Pages', 'Actions', 'getPageUrls');
+             * }
+             * ```
+             */
             Piwik_PostEvent('WidgetsList.addWidgets');
         }
     }