API docs progress

Controller -> SystemController for consistency

modules/backend/behaviors/UserPreferencesModel.php

@@ -4,16 +4,14 @@ use System\Behaviors\SettingsModel;
 use Backend\Models\UserPreference;
 
 /**
- * User Preferences model extension, identical to System.Behaviors.SettingsModel
- * except values are set against the logged in user's preferences via Backend\Models\UserPreference.
+ * User Preferences model extension, identical to System\Behaviors\SettingsModel
+ * except values are set against the logged in user's preferences via Backend\Models\UserPreference
  *
- * Usage:
+ * Add this the model class definition:
  *
- * In the model class definition:
- *
- *   public $implement = ['Backend.Behaviors.UserPreferencesModel'];
- *   public $settingsCode = 'author.plugin::code';
- *   public $settingsFields = 'fields.yaml';
+ *     public $implement = ['Backend.Behaviors.UserPreferencesModel'];
+ *     public $settingsCode = 'author.plugin::code';
+ *     public $settingsFields = 'fields.yaml';
  *
  */
 class UserPreferencesModel extends SettingsModel

modules/backend/classes/AuthManager.php

@@ -54,11 +54,11 @@ class AuthManager extends RainAuthManager
      * The callback function should register permissions by calling the manager's
      * registerPermissions() function. The manager instance is passed to the
      * callback function as an argument. Usage:
-     * <pre>
-     *   BackendAuth::registerCallback(function($manager){
-     *       $manager->registerPermissions([...]);
-     *   });
-     * </pre>
+     *
+     *     BackendAuth::registerCallback(function($manager){
+     *         $manager->registerPermissions([...]);
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public function registerCallback(callable $callback)

modules/backend/classes/BackendController.php

@@ -11,9 +11,15 @@ use October\Rain\Router\Helper as RouterHelper;
 use Closure;
 
 /**
- * The Backend controller class.
- * The base controller services back end pages.
+ * This is the master controller for all back-end pages.
+ * All requests that are prefixed with the backend URI pattern are sent here,
+ * then the next URI segments are analysed and the request is routed to the
+ * relevant back-end controller.
  *
+ * For example, a request with the URL `/backend/acme/blog/posts` will look
+ * for the `Posts` controller inside the `Acme.Blog` plugin.
+ *
+ * @see Backend\Classes\Controller Base class for back-end controllers
  * @package october\backend
  * @author Alexey Bobkov, Samuel Georges
  */

modules/backend/classes/NavigationManager.php

@@ -143,13 +143,13 @@ class NavigationManager
     /**
      * Registers a callback function that defines menu items.
      * The callback function should register menu items by calling the manager's
-     * registerMenuItems() function. The manager instance is passed to the
-     * callback function as an argument. Usage:
-     * <pre>
-     *   BackendMenu::registerCallback(function($manager){
-     *       $manager->registerMenuItems([...]);
-     *   });
-     * </pre>
+     * `registerMenuItems` method. The manager instance is passed to the callback
+     * function as an argument. Usage:
+     *
+     *     BackendMenu::registerCallback(function($manager){
+     *         $manager->registerMenuItems([...]);
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public function registerCallback(callable $callback)

modules/backend/classes/WidgetManager.php

@@ -93,7 +93,7 @@ class WidgetManager
     /**
      * Registers a single form form widget.
      * @param string $className Widget class name.
-     * @param array $widgetInfo Registration information, can contain an 'code' key.
+     * @param array $widgetInfo Registration information, can contain a `code` key.
      * @return void
      */
     public function registerFormWidget($className, $widgetInfo = null)
@@ -115,11 +115,11 @@ class WidgetManager
     /**
      * Manually registers form widget for consideration.
      * Usage:
-     * <pre>
-     *   WidgetManager::registerFormWidgets(function($manager){
-     *       $manager->registerFormWidget('Backend\FormWidgets\CodeEditor', 'codeeditor');
-     *   });
-     * </pre>
+     *
+     *     WidgetManager::registerFormWidgets(function($manager){
+     *         $manager->registerFormWidget('Backend\FormWidgets\CodeEditor', 'codeeditor');
+     *     });
+     *
      */
     public function registerFormWidgets(callable $definitions)
     {
@@ -202,14 +202,14 @@ class WidgetManager
     /**
      * Manually registers report widget for consideration.
      * Usage:
-     * <pre>
-     *   WidgetManager::registerReportWidgets(function($manager){
-     *       $manager->registerReportWidget('RainLab\GoogleAnalytics\ReportWidgets\TrafficOverview', [
-     *           'name'=>'Google Analytics traffic overview',
-     *           'context'=>'dashboard'
-     *       ]);
-     *   });
-     * </pre>
+     *
+     *     WidgetManager::registerReportWidgets(function($manager){
+     *         $manager->registerReportWidget('RainLab\GoogleAnalytics\ReportWidgets\TrafficOverview', [
+     *             'name'=>'Google Analytics traffic overview',
+     *             'context'=>'dashboard'
+     *         ]);
+     *     });
+     *
      */
     public function registerReportWidgets(callable $definitions)
     {

modules/cms/classes/CmsController.php

@@ -5,9 +5,11 @@ use Illuminate\Routing\Controller as ControllerBase;
 use Closure;
 
 /**
- * The CMS controller class.
- * The base controller services front end pages.
+ * This is the master controller for all front-end pages.
+ * All requests that have not been picked up already by the router will end up here,
+ * then the URL is passed to the front-end controller for processing.
  *
+ * @see Cms\Classes\Controller Front-end controller class
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
  */

modules/cms/classes/ComponentManager.php

@@ -72,13 +72,12 @@ class ComponentManager
     }
 
     /**
-     * Manually registers a widget for consideration.
+     * Manually registers a component for consideration.
      * Usage:
-     * <pre>
-     *   ComponentManager::registerComponents(function($manager){
-     *       $manager->registerComponent('October\Demo\Components\Test', 'testComponent');
-     *   });
-     * </pre>
+     *
+     *     ComponentManager::registerComponents(function($manager){
+     *         $manager->registerComponent('October\Demo\Components\Test', 'testComponent');
+     *     });
      *
      * @param callable $definitions
      * @return array Array values are class names.

modules/cms/twig/ComponentTokenParser.php

@@ -6,11 +6,9 @@ use Twig_TokenParser;
 use Twig_Error_Syntax;
 
 /**
- * Parser for the {% component %} Twig tag.
+ * Parser for the `{% component %}` Twig tag.
  *
- * <pre>
- *  {% component "pluginComponent" %}
- * </pre>
+ *     {% component "pluginComponent" %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -21,7 +19,6 @@ class ComponentTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/ContentTokenParser.php

@@ -6,15 +6,13 @@ use Twig_TokenParser;
 use Twig_Error_Syntax;
 
 /**
- * Parser for the {% content %} Twig tag.
+ * Parser for the `{% content %}` Twig tag.
  *
- * <pre>
- *  {% content "intro.htm" %}
+ *     {% content "intro.htm" %}
  *
- *  {% content "intro.md" name='John' %}
+ *     {% content "intro.md" name='John' %}
  *
- *  {% content "intro/txt" name='John', year=2013 %}
- * </pre>
+ *     {% content "intro/txt" name='John', year=2013 %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -25,7 +23,6 @@ class ContentTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/DefaultTokenParser.php

@@ -4,14 +4,12 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% default %} Twig tag.
+ * Parser for the `{% default %}` Twig tag.
  *
- * <pre>
- *  {% put head %}
- *    <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
- *    {% default %}
- *  {% endput %}
- * </pre>
+ *     {% put head %}
+ *         <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
+ *         {% default %}
+ *     {% endput %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -22,7 +20,6 @@ class DefaultTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/FrameworkTokenParser.php

@@ -4,11 +4,9 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% framework %} Twig tag.
+ * Parser for the `{% framework %}` Twig tag.
  *
- * <pre>
- *  {% framework %}
- * </pre>
+ *     {% framework %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -19,7 +17,6 @@ class FrameworkTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/PageTokenParser.php

@@ -4,7 +4,9 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% page %} Twig tag.
+ * Parser for the `{% page %}` Twig tag.
+ *
+ *     {% page %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -15,7 +17,6 @@ class PageTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/PartialTokenParser.php

@@ -6,15 +6,13 @@ use Twig_TokenParser;
 use Twig_Error_Syntax;
 
 /**
- * Parser for the {% partial %} Twig tag.
+ * Parser for the `{% partial %}` Twig tag.
  *
- * <pre>
- *  {% partial "sidebar" %}
+ *     {% partial "sidebar" %}
  *
- *  {% partial "sidebar" name='John' %}
+ *     {% partial "sidebar" name='John' %}
  *
- *  {% partial "sidebar" name='John', year=2013 %}
- * </pre>
+ *     {% partial "sidebar" name='John', year=2013 %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -25,7 +23,6 @@ class PartialTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/PlaceholderTokenParser.php

@@ -6,17 +6,15 @@ use Twig_TokenParser;
 use Twig_Error_Syntax;
 
 /**
- * Parser for the {% placeholder %} Twig tag.
+ * Parser for the `{% placeholder %}` Twig tag.
  *
- * <pre>
- *  {% placeholder head %}
+ *     {% placeholder head %}
  *
- *  or - use default placeholder content
+ * or - use default placeholder content
  *
- *  {% placeholder head %}
- *    <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
- *  {% endshowblock %}
- * </pre>
+ *     {% placeholder head %}
+ *         <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
+ *     {% endshowblock %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -27,7 +25,6 @@ class PlaceholderTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/PutTokenParser.php

@@ -4,20 +4,18 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% put %} Twig tag.
+ * Parser for the `{% put %}` Twig tag.
  *
- * <pre>
- *  {% put head %}
- *    <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
- *  {% endput %}
+ *     {% put head %}
+ *         <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
+ *     {% endput %}
  *
  * or
  *
- * {% put head %}
- *   <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
- *   {% default %}
- * {% endput %}
- * </pre>
+ *     {% put head %}
+ *         <link href="//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet"/>
+ *         {% default %}
+ *     {% endput %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -28,7 +26,6 @@ class PutTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/ScriptsTokenParser.php

@@ -4,11 +4,9 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% scripts %} Twig tag.
+ * Parser for the `{% scripts %}` Twig tag.
  *
- * <pre>
- *  {% scripts %}
- * </pre>
+ *     {% scripts %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -19,7 +17,6 @@ class ScriptsTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/cms/twig/StylesTokenParser.php

@@ -4,11 +4,9 @@ use Twig_Token;
 use Twig_TokenParser;
 
 /**
- * Parser for the {% styles %} Twig tag.
+ * Parser for the `{% styles %}` Twig tag.
  *
- * <pre>
- *  {% styles %}
- * </pre>
+ *     {% styles %}
  *
  * @package october\cms
  * @author Alexey Bobkov, Samuel Georges
@@ -19,7 +17,6 @@ class StylesTokenParser extends Twig_TokenParser
      * Parses a token and returns a node.
      *
      * @param Twig_Token $token A Twig_Token instance
-     *
      * @return Twig_NodeInterface A Twig_NodeInterface instance
      */
     public function parse(Twig_Token $token)

modules/system/behaviors/SettingsModel.php

@@ -8,13 +8,11 @@ use ApplicationException;
 /**
  * Settings model extension
  *
- * Usage:
+ * Add this the model class definition:
  *
- * In the model class definition:
- *
- *   public $implement = ['System.Behaviors.SettingsModel'];
- *   public $settingsCode = 'author_plugin_code';
- *   public $settingsFields = 'fields.yaml';
+ *     public $implement = ['System.Behaviors.SettingsModel'];
+ *     public $settingsCode = 'author_plugin_code';
+ *     public $settingsFields = 'fields.yaml';
  *
  */
 class SettingsModel extends ModelBehavior
@@ -47,11 +45,6 @@ class SettingsModel extends ModelBehavior
         $this->model->guard([]);
         $this->model->timestamps = false;
 
-        // Option A: (@todo Determine which is faster by benchmark)
-        // $relativePath = strtolower(str_replace('\\', '/', get_class($model)));
-        // $this->configPath = ['modules/' . $relativePath, 'plugins/' . $relativePath];
-
-        // Option B:
         $this->configPath = $this->guessConfigPathFrom($model);
 
         /*

modules/system/classes/CombineAssets.php

@@ -21,9 +21,26 @@ use ApplicationException;
 use DateTime;
 
 /**
- * Class used for combining JavaScript and StyleSheet
- * files.
+ * Combiner class used for combining JavaScript and StyleSheet files.
  *
+ * This works by taking a collection of asset locations, serializing them,
+ * then storing them in the session with a unique ID. The ID is then used
+ * to generate a URL to the `/combine` route via the system controller.
+ *
+ * When the combine route is hit, the unique ID is used to serve up the
+ * assets -- minified, compiled or both. Special E-Tags are used to prevent
+ * compilation and delivery of cached assets that are unchanged.
+ *
+ * Use the `CombineAssets::combine` method to combine your own assets.
+ *
+ * The functionality of this class is controlled by these config items:
+ *
+ * - cms.enableAssetCache - Cache untouched assets
+ * - cms.enableAssetMinify - Compress assets using minification
+ * - cms.enableAssetDeepHashing - Advanced caching of imports
+ *
+ * @see System\Classes\SystemController System controller
+ * @see https://octobercms.com/docs/services/session Session service
  * @package october\system
  * @author Alexey Bobkov, Samuel Georges
  */
@@ -147,6 +164,17 @@ class CombineAssets
     /**
      * Combines JavaScript or StyleSheet file references
      * to produce a page relative URL to the combined contents.
+     *
+     *     $assets = [
+     *         'assets/vendor/mustache/mustache.js',
+     *         'assets/js/vendor/jquery.ui.widget.js',
+     *         'assets/js/vendor/canvas-to-blob.js',
+     *     ];
+     *
+     *     CombineAssets::combine($assets, base_path('plugins/acme/blog'));
+     *
+     * @param array $assets Collection of assets
+     * @param string $localPath Prefix all assets with this path (optional)
      * @return string URL to contents.
      */
     public static function combine($assets = [], $localPath = null)
@@ -156,11 +184,24 @@ class CombineAssets
 
     /**
      * Combines a collection of assets files to a destination file
-     * @param array $assets
-     * @param string $destination
+     *
+     *     $assets = [
+     *         'assets/less/header.less',
+     *         'assets/less/footer.less',
+     *     ];
+     *
+     *     CombineAssets::combineToFile(
+     *         $assets,
+     *         base_path('themes/website/assets/theme.less'),
+     *         base_path('themes/website')
+     *     );
+     *
+     * @param array $assets Collection of assets
+     * @param string $destination Write the combined file to this location
+     * @param string $localPath Prefix all assets with this path (optional)
      * @return void
      */
-    public function combineToFile($assets = [], $destination)
+    public function combineToFile($assets = [], $destination, $localPath = null)
     {
         // Disable cache always
         $this->storagePath = null;
@@ -482,13 +523,13 @@ class CombineAssets
     /**
      * Registers a callback function that defines bundles.
      * The callback function should register bundles by calling the manager's
-     * registerBundle() function. Thi instance is passed to the
-     * callback function as an argument. Usage:
-     * <pre>
-     *   CombineAssets::registerCallback(function($combiner){
-     *       $combiner->registerBundle('~/modules/backend/assets/less/october.less');
-     *   });
-     * </pre>
+     * `registerBundle` method. Thi instance is passed to the callback 
+     * function as an argument. Usage:
+     *
+     *     CombineAssets::registerCallback(function($combiner){
+     *         $combiner->registerBundle('~/modules/backend/assets/less/october.less');
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public static function registerCallback(callable $callback)

modules/system/classes/MarkupManager.php

@@ -78,16 +78,16 @@ class MarkupManager
     /**
      * Registers a callback function that defines simple Twig extensions.
      * The callback function should register menu items by calling the manager's
-     * registerFunctions(), registerFilters(), registerTokenParsers() function.
-     * The manager instance is passed to the callback function as an argument. 
+     * `registerFunctions`, `registerFilters`, `registerTokenParsers` function.
+     * The manager instance is passed to the callback function as an argument.
      * Usage:
-     * <pre>
-     *   MarkupManager::registerCallback(function($manager){
-     *       $manager->registerFilters([...]);
-     *       $manager->registerFunctions([...]);
-     *       $manager->registerTokenParsers([...]);
-     *   });
-     * </pre>
+     *
+     *     MarkupManager::registerCallback(function($manager){
+     *         $manager->registerFilters([...]);
+     *         $manager->registerFunctions([...]);
+     *         $manager->registerTokenParsers([...]);
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public function registerCallback(callable $callback)

modules/system/classes/SettingsManager.php

@@ -191,12 +191,13 @@ class SettingsManager
      * Registers a callback function that defines setting items.
      * The callback function should register setting items by calling the manager's
      * registerSettingItems() function. The manager instance is passed to the
-     * callback function as an argument. Usage:
-     * <pre>
-     *   SettingsManager::registerCallback(function($manager){
-     *       $manager->registerSettingItems([...]);
-     *   });
-     * </pre>
+     * callback function as an argument.
+     * Usage:
+     *
+     *     SettingsManager::registerCallback(function($manager){
+     *         $manager->registerSettingItems([...]);
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public function registerCallback(callable $callback)

modules/system/classes/SystemController.php

@@ -7,12 +7,14 @@ use Illuminate\Routing\Controller as ControllerBase;
 use Exception;
 
 /**
- * The System controller class.
+ * The is the master controller for system related routing.
+ * It is currently only responsible for serving up the asset combiner contents.
  *
+ * @see System\Classes\CombineAssets Asset combiner class
  * @package october\system
  * @author Alexey Bobkov, Samuel Georges
  */
-class Controller extends ControllerBase
+class SystemController extends ControllerBase
 {
     /**
      * Combines JavaScript and StyleSheet assets.

modules/system/console/OctoberDown.php

@@ -5,6 +5,14 @@ use System\Classes\UpdateManager;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to tear down the database.
+ *
+ * This destroys all database tables that are registered for October and all plugins.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberDown extends Command
 {
 

modules/system/console/OctoberEnv.php

@@ -2,6 +2,15 @@
 
 use Illuminate\Console\Command;
 
+/**
+ * Console command to convert configuration to use .env files.
+ *
+ * This creates an .env file with some default configuration values, it also converts
+ * the existing PHP-based configuration files to use the `env` function for values.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberEnv extends Command
 {
 

modules/system/console/OctoberFresh.php

@@ -7,6 +7,14 @@ use Cms\Classes\ThemeManager;
 use Illuminate\Console\Command;
 use Symfony\Component\Console\Input\InputOption;
 
+/**
+ * Console command to remove boilerplate.
+ *
+ * This removes the demo theme and plugin. A great way to start a fresh project!
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberFresh extends Command
 {
     use \Illuminate\Console\ConfirmableTrait;

modules/system/console/OctoberInstall.php

@@ -18,6 +18,16 @@ use Illuminate\Encryption\Encrypter;
 use Symfony\Component\Console\Input\InputOption;
 use Exception;
 
+/**
+ * Console command to install October.
+ *
+ * This sets up October for the first time. It will prompt the user for several
+ * configuration items, including application URL and database config, and then
+ * perform a database migration.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberInstall extends Command
 {
     use \Illuminate\Console\ConfirmableTrait;

modules/system/console/OctoberMirror.php

@@ -7,11 +7,13 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Filesystem\Filesystem;
 
 /**
+ * Console command to implement a "public" folder.
+ *
  * This command will create symbolic links to files and directories
  * that are commonly required to be publicly available.
  *
- * It is experimental and currently undergoing testing,
- * see: https://github.com/octobercms/october/issues/1331
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
  */
 class OctoberMirror extends Command
 {

modules/system/console/OctoberUp.php

@@ -5,6 +5,14 @@ use System\Classes\UpdateManager;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to migrate the database.
+ *
+ * This builds up all database tables that are registered for October and all plugins.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberUp extends Command
 {
 

modules/system/console/OctoberUpdate.php

@@ -7,6 +7,16 @@ use System\Classes\UpdateManager;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to perform a system update.
+ *
+ * This updates October CMS and all plugins, database and files. It uses the
+ * October gateway to receive the files via a package manager, then saves
+ * the latest build number to the system.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class OctoberUpdate extends Command
 {
 

modules/system/console/OctoberUtil.php

@@ -9,18 +9,23 @@ use Symfony\Component\Console\Input\InputArgument;
 use System\Classes\CombineAssets;
 
 /**
- * Utility command
+ * Console command for other utility commands.
  *
- * Supported commands:
+ * This provides functionality that doesn't quite deserve its own dedicated
+ * console class. It is used mostly developer tools and maintenance tasks.
  *
- *   - purge thumbs: Deletes all thumbnail files in the uploads directory.
- *   - git pull: Perform "git pull" on all plugins and themes.
- *   - compile assets: Compile registered Language, LESS and JS files.
- *   - compile js: Compile registered JS files only.
- *   - compile less: Compile registered LESS files only.
- *   - compile scss: Compile registered SCSS files only.
- *   - compile lang: Compile registered Language files only.
+ * Currently supported commands:
  *
+ * - purge thumbs: Deletes all thumbnail files in the uploads directory.
+ * - git pull: Perform "git pull" on all plugins and themes.
+ * - compile assets: Compile registered Language, LESS and JS files.
+ * - compile js: Compile registered JS files only.
+ * - compile less: Compile registered LESS files only.
+ * - compile scss: Compile registered SCSS files only.
+ * - compile lang: Compile registered Language files only.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
  */
 class OctoberUtil extends Command
 {

modules/system/console/PluginInstall.php

@@ -6,6 +6,14 @@ use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 use System\Classes\PluginManager;
 
+/**
+ * Console command to install a new plugin.
+ *
+ * This adds a new plugin by requesting it from the October marketplace.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class PluginInstall extends Command
 {
 
@@ -19,7 +27,7 @@ class PluginInstall extends Command
      * The console command description.
      * @var string
      */
-    protected $description = 'Adds a new plugin.';
+    protected $description = 'Install a plugin from the October marketplace.';
 
     /**
      * Create a new command instance.

modules/system/console/PluginRefresh.php

@@ -6,6 +6,15 @@ use System\Classes\PluginManager;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to refresh a plugin.
+ *
+ * This destroys all database tables for a specific plugin, then builds them up again.
+ * It is a great way for developers to debug and develop new plugins.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class PluginRefresh extends Command
 {
 

modules/system/console/PluginRemove.php

@@ -7,6 +7,15 @@ use System\Classes\PluginManager;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to remove a plugin.
+ *
+ * This completely deletes an existing plugin, including database tables, files
+ * and directories.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class PluginRemove extends Command
 {
 

modules/system/console/ThemeInstall.php

@@ -8,6 +8,14 @@ use Illuminate\Console\Command;
 use Symfony\Component\Console\Input\InputArgument;
 use Exception;
 
+/**
+ * Console command to install a new theme.
+ *
+ * This adds a new theme by requesting it from the October marketplace.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class ThemeInstall extends Command
 {
     /**

modules/system/console/ThemeList.php

@@ -6,6 +6,14 @@ use Cms\Classes\Theme;
 use Cms\Classes\ThemeManager;
 use System\Classes\UpdateManager;
 
+/**
+ * Console command to list themes.
+ *
+ * This lists all the available themes in the system. It also shows the active theme.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class ThemeList extends Command
 {
     /**

modules/system/console/ThemeRemove.php

@@ -7,6 +7,14 @@ use Symfony\Component\Console\Input\InputArgument;
 use Illuminate\Console\Command;
 use Exception;
 
+/**
+ * Console command to remove a theme.
+ *
+ * This completely deletes an existing theme, including all files and directories.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class ThemeRemove extends Command
 {
 

modules/system/console/ThemeUse.php

@@ -5,6 +5,14 @@ use Illuminate\Console\Command;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 
+/**
+ * Console command to switch themes.
+ *
+ * This switches the active theme to another one, saved to the database.
+ *
+ * @package october\system
+ * @author Alexey Bobkov, Samuel Georges
+ */
 class ThemeUse extends Command
 {
     use \Illuminate\Console\ConfirmableTrait;

modules/system/models/MailTemplate.php

@@ -229,11 +229,11 @@ class MailTemplate extends Model
      * The callback function should register templates by calling the manager's
      * registerMailTemplates() function. Thi instance is passed to the
      * callback function as an argument. Usage:
-     * <pre>
-     *   MailTemplate::registerCallback(function($template){
-     *       $template->registerMailTemplates([...]);
-     *   });
-     * </pre>
+     *
+     *     MailTemplate::registerCallback(function($template){
+     *         $template->registerMailTemplates([...]);
+     *     });
+     *
      * @param callable $callback A callable function.
      */
     public static function registerCallback(callable $callback)

modules/system/routes.php

@@ -7,5 +7,5 @@ App::before(function ($request) {
     /*
      * Combine JavaScript and StyleSheet assets
      */
-    Route::any('combine/{file}', 'System\Classes\Controller@combine');
+    Route::any('combine/{file}', 'System\Classes\SystemController@combine');
 });