From 244aa061ffd3942d3b969e97a753860f42baf3db Mon Sep 17 00:00:00 2001
From: mark_story <mark@mark-story.com>
Date: Mon, 7 Jul 2014 20:21:53 -0400
Subject: [PATCH] Fix API doc errors in Datasource/

---
 src/Datasource/ConnectionManager.php   |  3 +--
 src/Datasource/EntityInterface.php     | 16 ++++++------
 src/Datasource/EntityTrait.php         | 34 +++++++++++++-------------
 src/Datasource/QueryCacher.php         | 10 ++++----
 src/Datasource/QueryTrait.php          | 22 ++++++++---------
 src/Datasource/RepositoryInterface.php |  4 +--
 src/Datasource/ResultSetDecorator.php  |  1 +
 7 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/src/Datasource/ConnectionManager.php b/src/Datasource/ConnectionManager.php
index 7fe40071150..e2297f1375b 100644
--- a/src/Datasource/ConnectionManager.php
+++ b/src/Datasource/ConnectionManager.php
@@ -52,12 +52,11 @@ class ConnectionManager {
  *
  * The connection will not be constructed until it is first used.
  *
- * @see \Cake\Core\StaticConfigTrait::config()
- *
  * @param string|array $key The name of the connection config, or an array of multiple configs.
  * @param array $config An array of name => config data for adapter.
  * @return mixed null when adding configuration and an array of configuration data when reading.
  * @throws \Cake\Error\Exception When trying to modify an existing config.
+ * @see \Cake\Core\StaticConfigTrait::config()
  */
 	public static function config($key, $config = null) {
 		if (is_array($config)) {
diff --git a/src/Datasource/EntityInterface.php b/src/Datasource/EntityInterface.php
index a04a2d27736..876582b21b8 100644
--- a/src/Datasource/EntityInterface.php
+++ b/src/Datasource/EntityInterface.php
@@ -49,7 +49,7 @@ public function &get($property);
  * Returns whether this entity contains a property named $property
  * regardless of if it is empty.
  *
- * @param string $property
+ * @param string $property The property to check.
  * @return bool
  */
 	public function has($property);
@@ -57,7 +57,7 @@ public function has($property);
 /**
  * Removes a property or list of properties from this entity
  *
- * @param string|array $property
+ * @param string|array $property The property to unset.
  * @return \Cake\ORM\
  */
 	public function unsetProperty($property);
@@ -68,7 +68,7 @@ public function unsetProperty($property);
  * If the properties argument is null, the currently hidden properties
  * will be returned. Otherwise the hidden properties will be set.
  *
- * @param null|array Either an array of properties to hide or null to get properties
+ * @param null|array $properties Either an array of properties to hide or null to get properties
  * @return array|\Cake\DataSource\EntityInterface
  */
 	public function hiddenProperties($properties = null);
@@ -79,7 +79,7 @@ public function hiddenProperties($properties = null);
  * If the properties argument is null, the currently virtual properties
  * will be returned. Otherwise the virtual properties will be set.
  *
- * @param null|array Either an array of properties to treat as virtual or null to get properties
+ * @param null|array $properties Either an array of properties to treat as virtual or null to get properties
  * @return array|\Cake\DataSource\EntityInterface
  */
 	public function virtualProperties($properties = null);
@@ -118,7 +118,7 @@ public function extract(array $properties, $onlyDirty = false);
  * dirty property in the entity
  *
  * @param string $property the field to set or check status for
- * @param null|bool true means the property was changed, false means
+ * @param null|bool $isDirty true means the property was changed, false means
  * it was not changed and null will make the function return current state
  * for that property
  * @return bool whether the property was changed or not
@@ -157,7 +157,7 @@ public function isNew($new = null);
  * This function returns true if there were no validation errors or false
  * otherwise.
  *
- * @param \Cake\Validation\Validator $validator
+ * @param \Cake\Validation\Validator $validator The validator to use when validating the entity.
  * @return bool
  */
 	public function validate(Validator $validator);
@@ -171,7 +171,7 @@ public function validate(Validator $validator);
  * When used as a setter, this method will return this entity instance for method
  * chaining.
  *
- * @param string|array $field
+ * @param string|array $field The field to get errors for.
  * @param string|array $errors The errors to be set for $field
  * @return array|\Cake\Datasource\EntityInterface
  */
@@ -184,7 +184,7 @@ public function errors($field = null, $errors = null);
  * `$entity->accessible('*', true)`  means that any property not specified already
  * will be accessible by default.
  *
- * @param string|array single or list of properties to change its accessibility
+ * @param string|array $property Either a single or list of properties to change its accessibility.
  * @param bool $set true marks the property as accessible, false will
  * mark it as protected.
  * @return \Cake\Datasource\EntityInterface|bool
diff --git a/src/Datasource/EntityTrait.php b/src/Datasource/EntityTrait.php
index 5116cd30aa1..3b8e17dc674 100644
--- a/src/Datasource/EntityTrait.php
+++ b/src/Datasource/EntityTrait.php
@@ -129,9 +129,9 @@ public function __set($property, $value) {
  * Returns whether this entity contains a property named $property
  * regardless of if it is empty.
  *
- * @see \Cake\ORM\Entity::has()
- * @param string $property
+ * @param string $property The property to check.
  * @return bool
+ * @see \Cake\ORM\Entity::has()
  */
 	public function __isset($property) {
 		return $this->has($property);
@@ -140,7 +140,7 @@ public function __isset($property) {
 /**
  * Removes a property from this entity
  *
- * @param string $property
+ * @param string $property The property to unset
  * @return void
  */
 	public function __unset($property) {
@@ -273,7 +273,7 @@ public function &get($property) {
  *		$entity->has('last_name'); // false
  * }}}
  *
- * @param string $property
+ * @param string $property The property to check.
  * @return bool
  */
 	public function has($property) {
@@ -289,8 +289,8 @@ public function has($property) {
  *
  * ``$entity->unsetProperty(['name', 'last_name']);``
  *
- * @param string|array $property
- * @return \Cake\ORM\
+ * @param string|array $property The property to unset.
+ * @return \Cake\DataSource\EntityInterface
  */
 	public function unsetProperty($property) {
 		$property = (array)$property;
@@ -307,7 +307,7 @@ public function unsetProperty($property) {
  * If the properties argument is null, the currently hidden properties
  * will be returned. Otherwise the hidden properties will be set.
  *
- * @param null|array Either an array of properties to hide or null to get properties
+ * @param null|array $properties Either an array of properties to hide or null to get properties
  * @return array|\Cake\DataSource\EntityInterface
  */
 	public function hiddenProperties($properties = null) {
@@ -324,7 +324,7 @@ public function hiddenProperties($properties = null) {
  * If the properties argument is null, the currently virtual properties
  * will be returned. Otherwise the virtual properties will be set.
  *
- * @param null|array Either an array of properties to treat as virtual or null to get properties
+ * @param null|array $properties Either an array of properties to treat as virtual or null to get properties
  * @return array|\Cake\DataSource\EntityInterface
  */
 	public function virtualProperties($properties = null) {
@@ -389,7 +389,7 @@ public function jsonSerialize() {
 /**
  * Implements isset($entity);
  *
- * @param mixed $offset
+ * @param mixed $offset The offset to check.
  * @return bool Success
  */
 	public function offsetExists($offset) {
@@ -399,7 +399,7 @@ public function offsetExists($offset) {
 /**
  * Implements $entity[$offset];
  *
- * @param mixed $offset
+ * @param mixed $offset The offset to get.
  * @return mixed
  */
 	public function &offsetGet($offset) {
@@ -409,8 +409,8 @@ public function &offsetGet($offset) {
 /**
  * Implements $entity[$offset] = $value;
  *
- * @param mixed $offset
- * @param mixed $value
+ * @param mixed $offset The offset to set.
+ * @param mixed $value The value to set.
  * @return void
  */
 	public function offsetSet($offset, $value) {
@@ -420,7 +420,7 @@ public function offsetSet($offset, $value) {
 /**
  * Implements unset($result[$offset);
  *
- * @param mixed $offset
+ * @param mixed $offset The offset to remove.
  * @return void
  */
 	public function offsetUnset($offset) {
@@ -467,7 +467,7 @@ public function extract(array $properties, $onlyDirty = false) {
  * dirty property in the entity
  *
  * @param string $property the field to set or check status for
- * @param null|bool true means the property was changed, false means
+ * @param null|bool $isDirty true means the property was changed, false means
  * it was not changed and null will make the function return current state
  * for that property
  * @return bool whether the property was changed or not
@@ -531,7 +531,7 @@ public function isNew($new = null) {
  * This function returns true if there were no validation errors or false
  * otherwise.
  *
- * @param \Cake\Validation\Validator $validator
+ * @param \Cake\Validation\Validator $validator The validator to use when validating the entity.
  * @return bool
  */
 	public function validate(Validator $validator) {
@@ -567,7 +567,7 @@ public function validate(Validator $validator) {
  * When used as a setter, this method will return this entity instance for method
  * chaining.
  *
- * @param string|array $field
+ * @param string|array $field The field to get errors for, or the array of errors to set.
  * @param string|array $errors The errors to be set for $field
  * @return array|\Cake\Datasource\EntityInterface
  */
@@ -653,7 +653,7 @@ protected function _nestedErrors($field) {
  * $entity->accessible('id'); // Returns whether it can be set or not
  * }}}
  *
- * @param string|array single or list of properties to change its accessibility
+ * @param string|array $property single or list of properties to change its accessibility
  * @param bool $set true marks the property as accessible, false will
  * mark it as protected.
  * @return \Cake\Datasource\EntityInterface|bool
diff --git a/src/Datasource/QueryCacher.php b/src/Datasource/QueryCacher.php
index 5293c1b7d76..4b3d9771966 100644
--- a/src/Datasource/QueryCacher.php
+++ b/src/Datasource/QueryCacher.php
@@ -31,8 +31,8 @@ class QueryCacher {
 /**
  * Constructor.
  *
- * @param string|\Closure $key
- * @param string|CacheEngine $config
+ * @param string|\Closure $key The key or function to generate a key.
+ * @param string|CacheEngine $config The cache config name or cache engine instance.
  * @throws RuntimeException
  */
 	public function __construct($key, $config) {
@@ -67,7 +67,7 @@ public function fetch($query) {
  * Store the result set into the cache.
  *
  * @param object $query The query the cache read is for.
- * @param \Traversable The result set to store.
+ * @param \Traversable $results The result set to store.
  * @return void
  */
 	public function store($query, Traversable $results) {
@@ -79,9 +79,9 @@ public function store($query, Traversable $results) {
 /**
  * Get/generate the cache key.
  *
- * @param object $query
+ * @param object $query The query to generate a key for.
  * @return string
- * @throws RuntimeException
+ * @throws \RuntimeException
  */
 	protected function _resolveKey($query) {
 		if (is_string($this->_key)) {
diff --git a/src/Datasource/QueryTrait.php b/src/Datasource/QueryTrait.php
index 8fb68ae754e..62a638c6611 100644
--- a/src/Datasource/QueryTrait.php
+++ b/src/Datasource/QueryTrait.php
@@ -178,7 +178,7 @@ public function cache($key, $config = 'default') {
  * Sets the query instance to be the eager loaded query. If no argument is
  * passed, the current configured query `_eagerLoaded` value is returned.
  *
- * @param bool $value
+ * @param bool $value Whether or not to eager load.
  * @return \Cake\ORM\Query
  */
 	public function eagerLoaded($value = null) {
@@ -248,9 +248,9 @@ public function toArray() {
  * If the third argument is set to true, it will erase previous map reducers
  * and replace it with the arguments passed.
  *
- * @param callable $mapper
- * @param callable $reducer
- * @param bool $overwrite
+ * @param callable $mapper The mapper callable.
+ * @param callable $reducer The reducing function.
+ * @param bool $overwrite Set to true to overwrite existing map + reduce functions.
  * @return \Cake\Datasource\QueryTrait|array
  * @see \Cake\Collection\Iterator\MapReduce for details on how to use emit data to the map reducer.
  */
@@ -288,20 +288,20 @@ public function mapReduce(callable $mapper = null, callable $reducer = null, $ov
  * {{{
  * //Return all results from the table indexed by id
  * $query->select(['id', 'name'])->formatResults(function($results, $query) {
- *	return $results->indexBy('id');
+ *   return $results->indexBy('id');
  * });
  *
  * //Add a new column to the ResultSet
  * $query->select(['name', 'birth_date'])->formatResults(function($results, $query) {
- *	return $results->map(function($row) {
- *		$row['age'] = $row['birth_date']->diff(new DateTime)->y;
- *		return $row;
- *	});
+ *   return $results->map(function($row) {
+ *     $row['age'] = $row['birth_date']->diff(new DateTime)->y;
+ *     return $row;
+ *   });
  * });
  * }}}
  *
- * @param callable $formatter
- * @param bool|int $mode
+ * @param callable $formatter The formatting callable.
+ * @param bool|int $mode Whether or not to overwrite, append or prepend the formatter.
  * @return \Cake\Datasource\QueryTrait|array
  */
 	public function formatResults(callable $formatter = null, $mode = 0) {
diff --git a/src/Datasource/RepositoryInterface.php b/src/Datasource/RepositoryInterface.php
index d9aff9097c0..f31475766ad 100644
--- a/src/Datasource/RepositoryInterface.php
+++ b/src/Datasource/RepositoryInterface.php
@@ -113,8 +113,8 @@ public function exists($conditions);
  * returns the same entity after a successful save or false in case
  * of any error.
  *
- * @param \Cake\Datasource\EntityInterface the entity to be saved
- * @param array|\ArrayAccess $options
+ * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
+ * @param array|\ArrayAccess $options The options to use when saving.
  * @return \Cake\Datasource\EntityInterface|bool
  */
 	public function save(EntityInterface $entity, $options = []);
diff --git a/src/Datasource/ResultSetDecorator.php b/src/Datasource/ResultSetDecorator.php
index c81af2f6225..6e5161dcf98 100644
--- a/src/Datasource/ResultSetDecorator.php
+++ b/src/Datasource/ResultSetDecorator.php
@@ -57,6 +57,7 @@ public function serialize() {
  * Part of Serializable interface.
  *
  * @param string $serialized Serialized object
+ * @return void
  */
 	public function unserialize($serialized) {
 		parent::__construct(unserialize($serialized));