Add missing documentation comment blocks for fired events (#4788)

Credit to @mjauvin.

Author: mjauvin

modules/backend/classes/Controller.php

@@ -242,8 +242,24 @@ public function run($action = null, $params = [])
             }
         }
 
-        /*
-         * Extensibility
+        /**
+         * @event backend.page.beforeDisplay
+         * Provides an opportunity to override backend page content
+         *
+         * Example usage:
+         *
+         *     Event::listen('backend.page.beforeDisplay', function ((\Backend\Classes\Controller) $backendController, (string) $action, (array) $params) {
+         *         trace_log('redirect all backend pages to google');
+         *         return \Redirect::to('https://google.com');
+         *     });
+         *
+         * Or
+         *
+         *     $backendController->bindEvent('page.beforeDisplay', function ((string) $action, (array) $params) {
+         *         trace_log('redirect all backend pages to google');
+         *         return \Redirect::to('https://google.com');
+         *     });
+         *
          */
         if ($event = $this->fireSystemEvent('backend.page.beforeDisplay', [$action, $params])) {
             return $event;

modules/backend/classes/NavigationManager.php

@@ -100,8 +100,18 @@ protected function loadItems()
             $this->registerMenuItems($id, $items);
         }
 
-        /*
-         * Extensibility
+        /**
+         * @event backend.menu.extendItems
+         * Provides an opportunity to manipulate the backend navigation
+         *
+         * Example usage:
+         *
+         *     Event::listen('backend.menu.extendItems', function ((\Backend\Classes\NavigationManager) $navigationManager) {
+         *         $navigationManager->addMainMenuItems(...)
+         *         $navigationManager->addSideMenuItems(...)
+         *         $navigationManager->removeMainMenuItem(...)
+         *     });
+         *
          */
         Event::fire('backend.menu.extendItems', [$this]);
 

modules/backend/models/User.php

@@ -136,6 +136,18 @@ public function afterCreate()
     public function afterLogin()
     {
         parent::afterLogin();
+
+        /**
+         * @event backend.user.login
+         * Provides an opportunity to interact with the Backend User model after the user has logged in
+         *
+         * Example usage:
+         *
+         *     Event::listen('backend.user.login', function ((\Backend\Models\User) $user) {
+         *         Flash::success(sprintf('Welcome %s!', $user->getFullNameAttribute()));
+         *     });
+         *
+         */
         Event::fire('backend.user.login', [$this]);
     }
 

modules/backend/routes.php

@@ -4,8 +4,17 @@
  * Register Backend routes before all user routes.
  */
 App::before(function ($request) {
-    /*
-     * Extensibility
+
+    /**
+     * @event backend.beforeRoute
+     * Fires before backend routes get added
+     *
+     * Example usage:
+     *
+     *     Event::listen('backend.beforeRoute', function () {
+     *         // your code here
+     *     });
+     *
      */
     Event::fire('backend.beforeRoute');
 
@@ -25,8 +34,16 @@
      */
     Route::any(Config::get('cms.backendUri', 'backend'), 'Backend\Classes\BackendController@run')->middleware('web');
 
-    /*
-     * Extensibility
+    /**
+     * @event backend.route
+     * Fires after backend routes have been added
+     *
+     * Example usage:
+     *
+     *     Event::listen('backend.route', function () {
+     *         // your code here
+     *     });
+     *
      */
     Event::fire('backend.route');
 });

modules/cms/routes.php

@@ -4,8 +4,17 @@
  * Register CMS routes before all user routes.
  */
 App::before(function ($request) {
-    /*
-     * Extensibility
+
+    /**
+     * @event cms.beforeRoute
+     * Fires before cms routes get added
+     *
+     * Example usage:
+     *
+     *     Event::listen('cms.beforeRoute', function () {
+     *         // your code here
+     *     });
+     *
      */
     Event::fire('cms.beforeRoute');
 
@@ -15,8 +24,16 @@
      */
     Route::any('{slug}', 'Cms\Classes\CmsController@run')->where('slug', '(.*)?')->middleware('web');
 
-    /*
-     * Extensibility
+    /**
+     * @event cms.route
+     * Fires after cms routes get added
+     *
+     * Example usage:
+     *
+     *     Event::listen('cms.route', function () {
+     *         // your code here
+     *     });
+     *
      */
     Event::fire('cms.route');
 });

modules/cms/twig/Extension.php

@@ -193,6 +193,19 @@ public function displayBlock($name, $default = null)
             return $default;
         }
 
+        /**
+         * @event cms.block.render
+         * Provides an opportunity to modify the rendered block content
+         *
+         * Example usage:
+         *
+         *     Event::listen('cms.block.render', function ((string) $name, (string) $result) {
+         *         if ($name === 'myBlockName') {
+         *             return 'my custom content';
+         *         }
+         *     });
+         *
+         */
         if ($event = Event::fire('cms.block.render', [$name, $result], true)) {
             $result = $event;
         }

modules/system/classes/CombineAssets.php

@@ -411,8 +411,16 @@ protected function prepareRequest(array $assets, $localPath = null)
      */
     protected function prepareCombiner(array $assets, $rewritePath = null)
     {
-        /*
-         * Extensibility
+        /**
+         * @event cms.combiner.beforePrepare
+         * Provides an opportunity to interact with the asset combiner before assets are combined
+         *
+         * Example usage:
+         *
+         *     Event::listen('cms.combiner.beforePrepare', function ((\System\Classes\CombineAssets) $assetCombiner, (array) $assets) {
+         *         $assetCombiner->registerFilter(...)
+         *     });
+         *
          */
         Event::fire('cms.combiner.beforePrepare', [$this, $assets]);
 
@@ -809,10 +817,19 @@ protected function getCacheKey(array $assets)
             $cacheKey .= $this->getDeepHashFromAssets($assets);
         }
 
-        /*
-         * Extensibility
-         */
         $dataHolder = (object) ['key' => $cacheKey];
+
+        /**
+         * @event cms.combiner.getCacheKey
+         * Provides an opportunity to modify the asset combiner's cache key
+         *
+         * Example usage:
+         *
+         *     Event::listen('cms.combiner.getCacheKey', function ((\System\Classes\CombineAssets) $assetCombiner, (stdClass) $dataHolder) {
+         *         $dataHolder->key = rand();
+         *     });
+         *
+         */
         Event::fire('cms.combiner.getCacheKey', [$this, $dataHolder]);
         $cacheKey = $dataHolder->key;
 

modules/system/classes/SettingsManager.php

@@ -109,8 +109,17 @@ protected function loadItems()
             $this->registerSettingItems($id, $items);
         }
 
-        /*
-         * Extensibility
+        /**
+         * @event system.settings.extendItems
+         * Provides an opportunity to manipulate the system settings manager
+         *
+         * Example usage:
+         *
+         *     Event::listen('system.settings.extendItems', function ((\System\Classes\SettingsManager) $settingsManager) {
+         *         $settingsManager->addSettingItem(...)
+         *         $settingsManager->removeSettingItem(...)
+         *     });
+         *
          */
         Event::fire('system.settings.extendItems', [$this]);
 

modules/system/traits/ConfigMaker.php

@@ -67,8 +67,19 @@ public function makeConfig($configFile = [], $requiredConfig = [])
 
             $config = Yaml::parseFile($configFile);
 
-            /*
-             * Extensibility
+            /**
+             * @event system.extendConfigFile
+             * Provides an opportunity to modify config files
+             *
+             * Example usage:
+             *
+             *     Event::listen('system.extendConfigFile', function ((string) $path, (array) $config) {
+             *         if ($path === '/plugins/author/plugin-name/controllers/mycontroller/config_relation.yaml') {
+             *             unset($config['property_value']['view']['recordUrl']);
+             *             return $config;
+             *         }
+             *     });
+             *
              */
             $publicFile = File::localToPublic($configFile);
             if ($results = Event::fire('system.extendConfigFile', [$publicFile, $config])) {