Start fixing docblock errors found from apigen

src/Cache/Cache.php

@@ -412,6 +412,9 @@ class Cache {
  *   the cache key is empty. Can be any callable type supported by your PHP.
  * @param string $config The cache configuration to use for this operation.
  *   Defaults to default.
+ * @return mixed If the key is found: the cached data, false if the data
+ *   missing/expired, or an error.  If the key is not found: boolean of the
+ *   success of the write
  */
 	public static function remember($key, $callable, $config = 'default') {
 		$existing = self::read($key, $config);

src/Collection/CollectionTrait.php

@@ -214,11 +214,11 @@ trait CollectionTrait {
 /**
  * Folds the values in this collection to a single value, as the result of
  * applying the callback function to all elements. $zero is the initial state
- * of the reduction, and each successive step should of it should be returned
+ * of the reduction, and each successive step of it should be returned
  * by the callback function.
  *
- * The callback function is
- *
+ * @param callable $c The callback function to be called
+ * @param mixed $zero The state of reduction
  * @return void
  */
 	public function reduce(callable $c, $zero) {
@@ -284,6 +284,7 @@ trait CollectionTrait {
  * @param integer $type the type of comparison to perform, either SORT_STRING
  * SORT_NUMERIC or SORT_NATURAL
  * @see \Cake\Collection\Collection::sortBy()
+ * @return mixed The value of the top element in the collection
  */
 	public function max($callback, $type = SORT_NUMERIC) {
 		$sorted = new SortIterator($this, $callback, SORT_DESC, $type);
@@ -313,6 +314,7 @@ trait CollectionTrait {
  * @param integer $type the type of comparison to perform, either SORT_STRING
  * SORT_NUMERIC or SORT_NATURAL
  * @see \Cake\Collection\Collection::sortBy()
+ * @return mixed The value of the bottom element in the collection
  */
 	public function min($callback, $type = SORT_NUMERIC) {
 		$sorted = new SortIterator($this, $callback, SORT_ASC, $type);

src/Console/Command/Task/ExtractTask.php

@@ -502,6 +502,7 @@ class ExtractTask extends Shell {
  * @param array $rules the set of validation rules for the field
  * @param string $file the file name where this validation rule was found
  * @param string $domain default domain to bind the validations to
+ * @param string $category the translation category
  * @return void
  */
 	protected function _processValidationRules($field, $rules, $file, $domain, $category = 'LC_MESSAGES') {

src/Console/Command/Task/ModelTask.php

@@ -142,6 +142,7 @@ class ModelTask extends BakeTask {
  * @param string $className Name of class you want model to be.
  * @param string $table Table name
  * @return Model Model instance
+ * @throws \Exception Will throw this until baking models works
  */
 	protected function _getModelObject($className, $table = null) {
 		if (!$table) {
@@ -195,6 +196,7 @@ class ModelTask extends BakeTask {
  * Handles interactive baking
  *
  * @return boolean
+ * @throws \Exception Will throw this until baking models works
  */
 	protected function _interactive() {
 		$this->hr();

src/Console/Command/UpgradeShell.php

@@ -210,7 +210,8 @@ class UpgradeShell extends Shell {
  * Replace all the App::uses() calls with `use`.
  *
  * @param string $file The file to search and replace.
- * @param boolean $dryRun Whether or not to do the thing.
+ * @param boolean $dryRun Whether or not to do the thing
+ * @return mixed Replacement of uses call
  */
 	protected function _replaceUses($file) {
 		$pattern = '#App::uses\([\'"]([a-z0-9_]+)[\'"],\s*[\'"]([a-z0-9/_]+)(?:\.([a-z0-9/_]+))?[\'"]\)#i';
@@ -260,6 +261,7 @@ class UpgradeShell extends Shell {
  * Strips the Cake prefix off of classes that no longer have it.
  *
  * @param array $matches
+ * @return array Class names with Cake prefixes removed
  */
 	protected function _mapClassName($matches) {
 		$rename = [
@@ -546,7 +548,8 @@ class UpgradeShell extends Shell {
 
 /**
  * Filter paths to remove webroot, Plugin, tmp directories.
- *
+ * @param array $paths A list of directory paths
+ * @param array $directories A list of directories to exlcude
  * @return array
  */
 	protected function _filterPaths($paths, $directories) {
@@ -563,6 +566,7 @@ class UpgradeShell extends Shell {
 /**
  * Adds the namespace to a given file.
  *
+ * @param string $path The path of the file's location
  * @param string $filePath The file to add a namespace to.
  * @param string $ns The base namespace to use.
  * @param boolean $dry Whether or not to operate in dry-run mode.
@@ -609,6 +613,7 @@ class UpgradeShell extends Shell {
  * Searches the paths and finds files based on extension.
  *
  * @param string $extensions
+ * @param array $exclude An array if filenames to exlcude
  * @return void
  */
 	protected function _findFiles($extensions = '', $exclude = []) {

src/basics.php

@@ -275,12 +275,8 @@ if (!function_exists('pr')) {
 if (!function_exists('am')) {
 
 /**
- * Merge a group of arrays
+ * Merge a group of arrays, accepts an unlimited amount of parameters
  *
- * @param array First array
- * @param array Second array
- * @param array Third array
- * @param array Etc...
  * @return array All array parameters merged into one
  * @link http://book.cakephp.org/2.0/en/development/debugging.html#am
  */