Add docblocks to flash methods

src/Controller/Component/FlashComponent.php

@@ -54,6 +54,22 @@ class FlashComponent extends Component {
 		$this->_session = $collection->getController()->request->session();
 	}
 
+/**
+ * Used to set a session variable that can be used to output messages in the view.
+ *
+ * In your controller: $this->Flash->set('This has been saved');
+ *
+ * ### Options:
+ *
+ * - `key` The key to set under the session's Message key
+ * - `element` The element used to render the flash message
+ * - `class` The class to give the flash message whenever an element isn't supplied
+ * - `params` An array of variables to make available when using an element
+ *
+ * @param string $message Message to be flashed
+ * @param array $options An array of options
+ * @return void
+ */
 	public function set($message, array $options = []) {
 		$opts = array_merge($this->_defaultConfig, $options);
 
@@ -70,6 +86,15 @@ class FlashComponent extends Component {
 		]);
 	}
 
+
+/**
+ * Magic method for verbose flash methods based on element names.
+ *
+ * @param string $name Element name to use, omitting the "flash_" prefix.
+ * @param array $args Parameters to pass when calling `FlashComponent::set`.
+ * @return void
+ * @throws \Cake\Error\InternalErrorException If missing the flash message.
+*/
 	public function __call($name, $args) {
 		$options = ['element' => 'flash_' . $name];
 

src/View/Helper/FlashHelper.php

@@ -25,12 +25,63 @@ class FlashHelper extends Helper {
 
 	use StringTemplateTrait;
 
+/**
+ * Default config for this class
+ *
+ * @var array
+ */
 	protected $_defaultConfig = [
 		'templates' => [
 			'flash' => '<div id="{{key}}-message" class="message-{{class}}">{{message}}</div>'
 		]
 	];
 
+/**
+ * Used to render the message set in FlashCompnet::set()
+ *
+ * In your view: $this->Flash->out('somekey');
+ * Will default to flash if no param is passed
+ *
+ * You can pass additional information into the flash message generation. This allows you
+ * to consolidate all the parameters for a given type of flash message into the view.
+ *
+ * {{{
+ * echo $this->Flash->out('flash', ['class' => 'new-flash']);
+ * }}}
+ *
+ * The above would generate a flash message with a custom class name. Using $attrs['params'] you
+ * can pass additional data into the element rendering that will be made available as local variables
+ * when the element is rendered:
+ *
+ * {{{
+ * echo $this->Flash->out('flash', ['params' => ['name' => $user['User']['name']]]);
+ * }}}
+ *
+ * This would pass the current user's name into the flash message, so you could create personalized
+ * messages without the controller needing access to that data.
+ *
+ * Lastly you can choose the element that is rendered when creating the flash message. Using
+ * custom elements allows you to fully customize how flash messages are generated.
+ *
+ * {{{
+ * echo $this->Flash->out('flash', [element' => 'my_custom_element']);
+ * }}}
+ *
+ * If you want to use an element from a plugin for rendering your flash message you can do that using the
+ * plugin param:
+ *
+ * {{{
+ * echo $this->Session->flash('flash', [
+ *   'element' => 'my_custom_element',
+ *   'params' => ['plugin' => 'my_plugin'])
+ * ]);
+ * }}}
+ *
+ * @param string $key The [Message.]key you are rendering in the view.
+ * @param array $attrs Additional attributes to use for the creation of this flash message.
+ *    Supports the 'params', and 'element' keys that are used in the helper.
+ * @return string
+ */
 	public function out($key = 'flash', $attrs = []) {
 		$flash = $this->request->session()->read("Message.$key");
 		$this->request->session()->delete("Message.$key");