Fix API doc errors in ORM/

src/ORM/Association.php

@@ -286,7 +286,7 @@ abstract class Association {
  *
  * If no parameters are passed the current setting is returned.
  *
- * @param bool $dependent
+ * @param bool $dependent Set the dependent mode. Use null to read the current state.
  * @return bool
  */
 	public function dependent($dependent = null) {
@@ -326,7 +326,7 @@ abstract class Association {
  * in the source table record.
  * If no arguments are passed, the currently configured type is returned.
  *
- * @param string $name
+ * @param string $name The name of the association property. Use null to read the current value.
  * @return string
  */
 	public function property($name = null) {
@@ -346,7 +346,7 @@ abstract class Association {
  * rendering any changes to this setting void.
  * If no arguments are passed, the currently configured strategy is returned.
  *
- * @param string $name
+ * @param string $name The strategy type. Use null to read the current value.
  * @return string
  * @throws \InvalidArgumentException When an invalid strategy is provided.
  */
@@ -446,11 +446,11 @@ abstract class Association {
  * Correctly nests a result row associated values into the correct array keys inside the
  * source results.
  *
- * @param array $row
+ * @param array $row The row to transform
  * @param string $nestKey The array key under which the results for this association
- * should be found
+ *   should be found
  * @param bool $joined Whether or not the row is a result of a direct join
- * with this association
+ *   with this association
  * @return array
  */
 	public function transformRow($row, $nestKey, $joined) {
@@ -468,9 +468,9 @@ abstract class Association {
  * with the default empty value according to whether the association was
  * joined or fetched externally.
  *
- * @param array $row
+ * @param array $row The row to set a default on.
  * @param bool $joined Whether or not the row is a result of a direct join
- * with this association
+ *   with this association
  * @return array
  */
 	public function defaultRowValue($row, $joined) {
@@ -487,8 +487,8 @@ abstract class Association {
  * configuration
  *
  * @param string|array $type the type of query to perform, if an array is passed,
- * it will be interpreted as the `$options` parameter
- * @param array $options
+ *   it will be interpreted as the `$options` parameter
+ * @param array $options The options to for the find
  * @see \Cake\ORM\Table::find()
  * @return \Cake\ORM\Query
  */
@@ -693,7 +693,7 @@ abstract class Association {
  * Proxies method calls to the target table.
  *
  * @param string $method name of the method to be invoked
- * @param array $args List of arguments passed to the function
+ * @param array $argument List of arguments passed to the function
  * @return mixed
  * @throws \BadMethodCallException
  */
@@ -735,7 +735,7 @@ abstract class Association {
  * - strategy: The name of strategy to use for finding target table records
  * - nestKey: The array key under which results will be found when transforming the row
  *
- * @param array $options
+ * @param array $options The options for eager loading.
  * @return \Closure
  */
 	public abstract function eagerLoader(array $options);
@@ -767,7 +767,7 @@ abstract class Association {
  * the saving operation to the target table.
  *
  * @param \Cake\ORM\Entity $entity the data to be saved
- * @param array|\ArrayObject $options
+ * @param array|\ArrayObject $options The options for saving associated data.
  * @return bool|Entity false if $entity could not be saved, otherwise it returns
  * the saved entity
  * @see Table::save()

src/ORM/Association/BelongsTo.php

@@ -67,7 +67,7 @@ class BelongsTo extends Association {
  * in the source table record.
  * If no arguments are passed, currently configured type is returned.
  *
- * @param string $name
+ * @param string $name The property name, use null to read the current property.
  * @return string
  */
 	public function property($name = null) {

src/ORM/Association/BelongsToMany.php

@@ -411,7 +411,7 @@ class BelongsToMany extends Association {
  *
  * @param \Cake\ORM\Entity $parentEntity the source entity containing the target
  * entities to be saved.
- * @param array|\Traversable list of entities to persist in target table and to
+ * @param array|\Traversable $entities list of entities to persist in target table and to
  * link to the parent entity
  * @param array $options list of options accepted by Table::save()
  * @throws \InvalidArgumentException if the property representing the association
@@ -777,12 +777,12 @@ class BelongsToMany extends Association {
 /**
  * Throws an exception should any of the passed entities is not persisted.
  *
- * @throws \InvalidArgumentException
  * @param \Cake\ORM\Entity $sourceEntity the row belonging to the `source` side
- * of this association
+ *   of this association
  * @param array $targetEntities list of entities belonging to the `target` side
- * of this association
+ *   of this association
  * @return bool
+ * @throws \InvalidArgumentException
  */
 	protected function _checkPersistenceStatus($sourceEntity, array $targetEntities) {
 		if ($sourceEntity->isNew() !== false) {
@@ -804,10 +804,12 @@ class BelongsToMany extends Association {
  * Returns the list of joint entities that exist between the source entity
  * and each of the passed target entities
  *
- * @param \Cake\ORM\Entity $sourceEntity
- * @param array $targetEntities
+ * @param \Cake\ORM\Entity $sourceEntity The row belonging to the source side
+ *   of this association.
+ * @param array $targetEntities The rows belonging to the target side of this
+ *   association.
  * @throws \InvalidArgumentException if any of the entities is lacking a primary
- * key value
+ *   key value
  * @return array
  */
 	protected function _collectJointEntities($sourceEntity, $targetEntities) {
@@ -859,7 +861,7 @@ class BelongsToMany extends Association {
  * Appends any conditions required to load the relevant set of records in the
  * target table query given a filter key and some filtering values.
  *
- * @param \Cake\ORM\Query target table's query
+ * @param \Cake\ORM\Query $query target table's query
  * @param string $key the fields that should be used for filtering
  * @param mixed $filter the value that should be used to match for $key
  * @return \Cake\ORM\Query
@@ -875,7 +877,7 @@ class BelongsToMany extends Association {
  * Generates a string used as a table field that contains the values upon
  * which the filter should be applied
  *
- * @param array $options
+ * @param array $options the options to use for getting the link field.
  * @return string
  */
 	protected function _linkField($options) {
@@ -914,7 +916,7 @@ class BelongsToMany extends Association {
  * If no arguments are passed the current configured name is returned. A default
  * name based of the associated tables will be generated if none found.
  *
- * @param string $name
+ * @param string $name The name of the junction table.
  * @return string
  */
 	protected function _junctionTableName($name = null) {

src/ORM/Association/ExternalAssociationTrait.php

@@ -66,6 +66,7 @@ trait ExternalAssociationTrait {
 /**
  * Sets the sort order in which target records should be returned.
  * If no arguments are passed the currently configured value is returned
+ *
  * @param mixed $sort A find() compatible order clause
  * @return mixed
  */

src/ORM/Association/HasOne.php

@@ -62,7 +62,7 @@ class HasOne extends Association {
  * in the source table record.
  * If no arguments are passed, currently configured type is returned.
  *
- * @param string $name
+ * @param string $name The name of the property. Pass null to read the current value.
  * @return string
  */
 	public function property($name = null) {

src/ORM/Association/SelectableAssociationTrait.php

@@ -25,7 +25,7 @@ trait SelectableAssociationTrait {
  * Returns true if the eager loading process will require a set of parent table's
  * primary keys in order to use them as a filter in the finder query.
  *
- * @param array $options
+ * @param array $options The options containing the strategy to be used.
  * @return bool true if a list of keys will be required
  */
 	public function requiresKeys(array $options = []) {
@@ -145,7 +145,7 @@ trait SelectableAssociationTrait {
  * Generates a string used as a table field that contains the values upon
  * which the filter should be applied
  *
- * @param array $options
+ * @param array $options The options for getting the link field.
  * @return string|array
  */
 	protected abstract function _linkField($options);

src/ORM/BehaviorRegistry.php

@@ -55,7 +55,7 @@ class BehaviorRegistry extends ObjectRegistry {
 /**
  * Constructor
  *
- * @param \Cake\ORM\Table $table
+ * @param \Cake\ORM\Table $table The table this registry is attached to
  */
 	public function __construct(Table $table) {
 		$this->_table = $table;
@@ -81,6 +81,7 @@ class BehaviorRegistry extends ObjectRegistry {
  *
  * @param string $class The classname that is missing.
  * @param string $plugin The plugin the behavior is missing in.
+ * @return void
  * @throws \Cake\ORM\Error\MissingBehaviorException
  */
 	protected function _throwMissingClassError($class, $plugin) {
@@ -120,7 +121,7 @@ class BehaviorRegistry extends ObjectRegistry {
  * Methods starting with `_` will be ignored, as will methods
  * declared on Cake\ORM\Behavior
  *
- * @param \Cake\ORM\Behavior $instance
+ * @param \Cake\ORM\Behavior $instance The behavior to get methods from.
  * @param string $class The classname that is missing.
  * @param string $alias The alias of the object.
  * @return void

src/ORM/EagerLoader.php

@@ -439,7 +439,7 @@ class EagerLoader {
  *
  * @param array $external the list of external associations to be loaded
  * @param \Cake\ORM\Query $query The query from which the results where generated
- * @param BufferedStatement $statement
+ * @param BufferedStatement $statement The statement to work on
  * @return array
  */
 	protected function _collectKeys($external, $query, $statement) {
@@ -477,8 +477,8 @@ class EagerLoader {
  * Helper function used to iterate an statement and extract the columns
  * defined in $collectKeys
  *
- * @param \Cake\Database\StatementInterface $statement
- * @param array $collectKeys
+ * @param \Cake\Database\StatementInterface $statement The statement to read from.
+ * @param array $collectKeys The keys to collect
  * @return array
  */
 	protected function _groupKeys($statement, $collectKeys) {

src/ORM/EntityValidator.php

@@ -34,7 +34,7 @@ class EntityValidator {
 /**
  * Constructor.
  *
- * @param \Cake\ORM\Table $table
+ * @param \Cake\ORM\Table $table The table this validator is for
  */
 	public function __construct(Table $table) {
 		$this->_table = $table;
@@ -130,8 +130,8 @@ class EntityValidator {
  * If not empty it will construct a default validation object or get one with
  * the name passed in the key
  *
- * @param \Cake\ORM\Entity The entity to validate
- * @param \ArrayObject|array $options
+ * @param \Cake\ORM\Entity $entity The entity to validate
+ * @param \ArrayObject|array $options The option for processing validation
  * @return bool true if the entity is valid, false otherwise
  */
 	protected function _processValidation($entity, $options) {

src/ORM/Marshaller.php

@@ -53,7 +53,7 @@ class Marshaller {
 /**
  * Constructor.
  *
- * @param \Cake\ORM\Table $table
+ * @param \Cake\ORM\Table $table The table this marshaller is for.
  * @param bool $safe Whether or not this marshaller is in safe mode
  */
 	public function __construct(Table $table, $safe = false) {
@@ -128,7 +128,7 @@ class Marshaller {
 /**
  * Create a new sub-marshaller and marshal the associated data.
  *
- * @param \Cake\ORM\Association $assoc
+ * @param \Cake\ORM\Association $assoc The association to marshall
  * @param array $value The data to hydrate
  * @param array $include The associations to include.
  * @return mixed
@@ -327,8 +327,8 @@ class Marshaller {
 /**
  * Creates a new sub-marshaller and merges the associated data.
  *
- * @param \Cake\Datasource\EntityInterface $original
- * @param \Cake\ORM\Association $assoc
+ * @param \Cake\Datasource\EntityInterface $original The original entity
+ * @param \Cake\ORM\Association $assoc The association to merge
  * @param array $value The data to hydrate
  * @param array $include The associations to include.
  * @return mixed
@@ -354,8 +354,8 @@ class Marshaller {
  * Creates a new sub-marshaller and merges the associated data for a BelongstoMany
  * association.
  *
- * @param \Cake\Datasource\EntityInterface $original
- * @param \Cake\ORM\Association $assoc
+ * @param \Cake\Datasource\EntityInterface $original The original entity
+ * @param \Cake\ORM\Association $assoc The association to marshall
  * @param array $value The data to hydrate
  * @param array $include The associations to include.
  * @return mixed

src/ORM/Query.php

@@ -99,8 +99,8 @@ class Query extends DatabaseQuery {
 /**
  * Constuctor
  *
- * @param \Cake\Database\Connection $connection
- * @param \Cake\ORM\Table $table
+ * @param \Cake\Database\Connection $connection The connection object
+ * @param \Cake\ORM\Table $table The table this query is starting on
  */
 	public function __construct($connection, $table) {
 		parent::__construct($connection);
@@ -119,7 +119,7 @@ class Query extends DatabaseQuery {
  *
  * This method returns the same query object for chaining.
  *
- * @param \Cake\ORM\Table $table
+ * @param \Cake\ORM\Table $table The table to pull types from
  * @return $this
  */
 	public function addDefaultTypes(Table $table) {
@@ -139,7 +139,8 @@ class Query extends DatabaseQuery {
  * and storing containments. If called with no arguments, it will return the
  * currently configured instance.
  *
- * @param \Cake\ORM\EagerLoader $instance
+ * @param \Cake\ORM\EagerLoader $instance The eager loader to use. Pass null
+ *   to get the current eagerloader.
  * @return \Cake\ORM\EagerLoader|$this
  */
 	public function eagerLoader(EagerLoader $instance = null) {
@@ -346,7 +347,7 @@ class Query extends DatabaseQuery {
  * If the field is already aliased, then it will not be changed.
  * If no $alias is passed, the default table for this query will be used.
  *
- * @param string $field
+ * @param string $field The field to alias
  * @param string $alias the alias used to prefix the field
  * @return array
  */
@@ -374,8 +375,8 @@ class Query extends DatabaseQuery {
  * Runs `aliasfield()` for each field in the provided list and returns
  * the result under a single array.
  *
- * @param array $fields
- * @param string $defaultAlias
+ * @param array $fields The fields to alias
+ * @param string $defaultAlias The default alias
  * @return array
  */
 	public function aliasFields($fields, $defaultAlias = null) {
@@ -507,7 +508,7 @@ class Query extends DatabaseQuery {
  * The callback will receive as first argument a clone of this query and not this
  * query itself.
  *
- * @param callable $counter
+ * @param callable $counter The counter value
  * @return $this
  */
 	public function counter($counter) {

src/ORM/ResultSet.php

@@ -122,7 +122,7 @@ class ResultSet implements Countable, Iterator, Serializable, JsonSerializable {
  * Constructor
  *
  * @param \Cake\ORM\Query $query Query from where results come
- * @param \Cake\Database\StatementInterface $statement
+ * @param \Cake\Database\StatementInterface $statement The statement to fetch from
  */
 	public function __construct($query, $statement) {
 		$repository = $query->repository();
@@ -241,6 +241,7 @@ class ResultSet implements Countable, Iterator, Serializable, JsonSerializable {
  * Part of Serializable interface.
  *
  * @param string $serialized Serialized object
+ * @return void
  */
 	public function unserialize($serialized) {
 		$this->_results = unserialize($serialized);
@@ -431,8 +432,8 @@ class ResultSet implements Countable, Iterator, Serializable, JsonSerializable {
  * Casts all values from a row brought from a table to the correct
  * PHP type.
  *
- * @param Table $table
- * @param array $values
+ * @param Table $table The table object
+ * @param array $values The values to cast
  * @return array
  */
 	protected function _castValues($table, $values) {

src/ORM/Table.php

@@ -311,7 +311,7 @@ class Table implements RepositoryInterface, EventListener {
  * If an array is passed, a new \Cake\Database\Schema\Table will be constructed
  * out of it and used as the schema for this table.
  *
- * @param array|\Cake\Database\Schema\Table new schema to be used for this table
+ * @param array|\Cake\Database\Schema\Table $schema new schema to be used for this table
  * @return \Cake\Database\Schema\Table
  */
 	public function schema($schema = null) {
@@ -475,8 +475,7 @@ class Table implements RepositoryInterface, EventListener {
  * $this->removeBehavior('Tree');
  * }}}
  *
- * @param string $name    The alias that the behavior was added with.
- *
+ * @param string $name The alias that the behavior was added with.
  * @return void
  * @see \Cake\ORM\Behavior
  */
@@ -704,8 +703,8 @@ class Table implements RepositoryInterface, EventListener {
 /**
  * Returns the query as passed
  *
- * @param \Cake\ORM\Query $query
- * @param array $options
+ * @param \Cake\ORM\Query $query The query to find with
+ * @param array $options The options to use for the find
  * @return \Cake\ORM\Query
  */
 	public function findAll(Query $query, array $options) {
@@ -765,8 +764,8 @@ class Table implements RepositoryInterface, EventListener {
  * ]
  * }}}
  *
- * @param \Cake\ORM\Query $query
- * @param array $options
+ * @param \Cake\ORM\Query $query The query to find with
+ * @param array $options The options for the find
  * @return \Cake\ORM\Query
  */
 	public function findList(Query $query, array $options) {
@@ -808,8 +807,8 @@ class Table implements RepositoryInterface, EventListener {
  * ]);
  * }}}
  *
- * @param \Cake\ORM\Query $query
- * @param array $options
+ * @param \Cake\ORM\Query $query The query to find with
+ * @param array $options The options to find with
  * @return \Cake\ORM\Query
  */
 	public function findThreaded(Query $query, array $options) {
@@ -953,7 +952,8 @@ class Table implements RepositoryInterface, EventListener {
  * set is specified.
  *
  * @param string $name the name of the validation set to return
- * @param \Cake\Validation\Validator $validator
+ * @param \Cake\Validation\Validator $validator The validator instance to store,
+ *   use null to get a validator.
  * @return \Cake\Validation\Validator
  */
 	public function validator($name = 'default', Validator $validator = null) {
@@ -1114,8 +1114,8 @@ class Table implements RepositoryInterface, EventListener {
 /**
  * Performs the actual saving of an entity based on the passed options.
  *
- * @param \Cake\Datasource\EntityInterface the entity to be saved
- * @param array $options
+ * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
+ * @param array $options the options to use for the save operation
  * @return \Cake\Datasource\EntityInterface|bool
  */
 	protected function _processSave($entity, $options) {
@@ -1201,7 +1201,7 @@ class Table implements RepositoryInterface, EventListener {
 /**
  * Auxiliary function to handle the insert of an entity's data in the table
  *
- * @param \Cake\Datasource\EntityInterface the subject entity from were $data was extracted
+ * @param \Cake\Datasource\EntityInterface $entity the subject entity from were $data was extracted
  * @param array $data The actual data that needs to be saved
  * @return \Cake\Datasource\EntityInterface|bool
  * @throws \RuntimeException if not all the primary keys where supplied or could
@@ -1275,7 +1275,7 @@ class Table implements RepositoryInterface, EventListener {
 /**
  * Auxiliary function to handle the update of an entity's data in the table
  *
- * @param \Cake\Datasource\EntityInterface the subject entity from were $data was extracted
+ * @param \Cake\Datasource\EntityInterface $entity the subject entity from were $data was extracted
  * @param array $data The actual data that needs to be saved
  * @return \Cake\Datasource\EntityInterface|bool
  * @throws \InvalidArgumentException When primary key data is missing.

src/ORM/TableRegistry.php

@@ -184,7 +184,7 @@ class TableRegistry {
  * Set an instance.
  *
  * @param string $alias The alias to set.
- * @param \Cake\ORM\Table The table to set.
+ * @param \Cake\ORM\Table $object The table to set.
  * @return void
  */
 	public static function set($alias, Table $object) {