From e54cf7133b12a550e3888f49c716e6d9863c0fee Mon Sep 17 00:00:00 2001
From: Samuel Georges <sam@daftspunk.com>
Date: Tue, 14 Mar 2017 19:36:17 +1100
Subject: [PATCH] Improve some inline docs in preparation for API docs

---
 modules/backend/behaviors/ListController.php |  2 +-
 modules/backend/traits/FormModelSaver.php    | 37 +++++++++++---------
 modules/cms/classes/Theme.php                | 12 ++++++-
 modules/system/traits/AssetMaker.php         |  2 +-
 modules/system/traits/EventEmitter.php       |  6 ++--
 5 files changed, 37 insertions(+), 22 deletions(-)

diff --git a/modules/backend/behaviors/ListController.php b/modules/backend/behaviors/ListController.php
index 34fb146fe..7570e2f10 100644
--- a/modules/backend/behaviors/ListController.php
+++ b/modules/backend/behaviors/ListController.php
@@ -47,7 +47,7 @@ class ListController extends ControllerBehavior
     protected $filterWidgets = [];
 
     /**
-     * {@inheritDoc}
+     * @inheritDoc
      */
     protected $requiredProperties = ['listConfig'];
 
diff --git a/modules/backend/traits/FormModelSaver.php b/modules/backend/traits/FormModelSaver.php
index cff20d77c..842cff1f1 100644
--- a/modules/backend/traits/FormModelSaver.php
+++ b/modules/backend/traits/FormModelSaver.php
@@ -6,19 +6,9 @@ use October\Rain\Halcyon\Model as HalcyonModel;
 use October\Rain\Database\Model as DatabaseModel;
 
 /**
- * Form Model Saver Trait
- *
- * Special logic for applying form data (usually from postback) and
- * applying it to a model and its relationships. This is a customized,
- * safer and simplified version of $model->push().
- *
- * Usage:
- *
- *    $modelsToSave = $this->prepareModelsToSave($model, [...]);
- * 
- *    foreach ($modelsToSave as $modelToSave) {
- *        $modelToSave->save();
- *    }
+ * Implements special logic for processing form data, typically from from postback, and
+ * filling the model attributes and attributes of any related models. This is a
+ * customized, safer and simplified version of `$model->push()`.
  *
  * @package october\backend
  * @author Alexey Bobkov, Samuel Georges
@@ -31,6 +21,23 @@ trait FormModelSaver
      */
     protected $modelsToSave = [];
 
+    /**
+     * Takes a model and fills it with data from a multidimensional array.
+     * If an attribute is found to be a relationship, that relationship
+     * is also filled.
+     *
+     *     $modelsToSave = $this->prepareModelsToSave($model, [...]);
+     *
+     *     $test = 'cms.theme.getActiveTheme';
+     *
+     *     foreach ($modelsToSave as $modelToSave) {
+     *         $modelToSave->save();
+     *     }
+     *
+     * @param \October\Rain\Database\Model $model Model to fill.
+     * @param array $saveData Attribute values to fill model.
+     * @return array The collection of models to save.
+     */
     protected function prepareModelsToSave($model, $saveData)
     {
         $this->modelsToSave = [];
@@ -40,9 +47,7 @@ trait FormModelSaver
 
     /**
      * Sets a data collection to a model attributes, relations will also be set.
-     * @param array $saveData Data to save.
-     * @param \October\Rain\Database\Model $model Model to save to
-     * @return array The collection of models to save.
+     * @return void
      */
     protected function setModelAttributes($model, $saveData)
     {
diff --git a/modules/cms/classes/Theme.php b/modules/cms/classes/Theme.php
index 5b90964fc..8eba82044 100644
--- a/modules/cms/classes/Theme.php
+++ b/modules/cms/classes/Theme.php
@@ -141,7 +141,7 @@ class Theme
     /**
      * Returns the active theme code.
      * By default the active theme is loaded from the cms.activeTheme parameter,
-     * but this behavior can be overridden by the cms.theme.getActiveTheme event listeners.
+     * but this behavior can be overridden by the cms.theme.getActiveTheme event listener.
      * @return string
      * If the theme doesn't exist, returns null.
      */
@@ -171,6 +171,16 @@ class Theme
             }
         }
 
+        /**
+         * @event cms.theme.getActiveTheme
+         * Overrides the active theme code.
+         *
+         * If a value is returned from this halting event, it will be used as the active
+         * theme code. Example usage:
+         *
+         *     Event::listen('cms.theme.getActiveTheme', function() { return 'mytheme'; });
+         *
+         */
         $apiResult = Event::fire('cms.theme.getActiveTheme', [], true);
         if ($apiResult !== null) {
             $activeTheme = $apiResult;
diff --git a/modules/system/traits/AssetMaker.php b/modules/system/traits/AssetMaker.php
index 73510f9aa..d8a200e46 100644
--- a/modules/system/traits/AssetMaker.php
+++ b/modules/system/traits/AssetMaker.php
@@ -37,7 +37,7 @@ trait AssetMaker
     }
 
     /**
-     * Outputs <link> and <script> tags to load assets previously added with addJs and addCss method calls
+     * Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls
      * @param string $type Return an asset collection of a given type (css, rss, js) or null for all.
      * @return string
      */
diff --git a/modules/system/traits/EventEmitter.php b/modules/system/traits/EventEmitter.php
index 56942e293..054668b4c 100644
--- a/modules/system/traits/EventEmitter.php
+++ b/modules/system/traits/EventEmitter.php
@@ -20,13 +20,13 @@ trait EventEmitter
      *
      * For example:
      *
-     *   $this->fireSystemEvent('backend.list.myEvent', ['my value']);
+     *     $this->fireSystemEvent('backend.list.myEvent', ['my value']);
      *
      * Is equivalent to:
      *
-     *   $this->fireEvent('list.myEvent', ['myvalue'], true);
+     *     $this->fireEvent('list.myEvent', ['myvalue'], true);
      *
-     *   Event::fire('backend.list.myEvent', [$this, 'myvalue'], true);
+     *     Event::fire('backend.list.myEvent', [$this, 'myvalue'], true);
      *
      * @param string $event Event name
      * @param array $params Event parameters