Merge pull request #3681 from cakephp/api-doc-comments

Fix api docblocks for behaviors.

lib/Cake/Model/Behavior/AclBehavior.php

@@ -42,8 +42,8 @@ class AclBehavior extends ModelBehavior {
 /**
  * Sets up the configuration for the model, and loads ACL models if they haven't been already
  *
- * @param Model $model
- * @param array $config
+ * @param Model $model Model using this behavior.
+ * @param array $config Configuration options.
  * @return void
  */
 	public function setup(Model $model, $config = array()) {
@@ -70,7 +70,7 @@ public function setup(Model $model, $config = array()) {
 /**
  * Retrieves the Aro/Aco node for this model
  *
- * @param Model $model
+ * @param Model $model Model using this behavior.
  * @param string|array|Model $ref Array with 'model' and 'foreign_key', model object, or string value
  * @param string $type Only needed when Acl is set up as 'both', specify 'Aro' or 'Aco' to get the correct node
  * @return array
@@ -93,7 +93,7 @@ public function node(Model $model, $ref = null, $type = null) {
 /**
  * Creates a new ARO/ACO node bound to this record
  *
- * @param Model $model
+ * @param Model $model Model using this behavior.
  * @param boolean $created True if this is a new record
  * @param array $options Options passed from Model::save().
  * @return void
@@ -125,7 +125,7 @@ public function afterSave(Model $model, $created, $options = array()) {
 /**
  * Destroys the ARO/ACO node bound to the deleted record
  *
- * @param Model $model
+ * @param Model $model Model using this behavior.
  * @return void
  */
 	public function afterDelete(Model $model) {

lib/Cake/Model/Behavior/TranslateBehavior.php

@@ -367,7 +367,7 @@ public function beforeSave(Model $Model, $options = array()) {
  * and to allow translations to be persisted even when validation
  * is disabled.
  *
- * @param Model $Model
+ * @param Model $Model Model using this behavior.
  * @return void
  */
 	protected function _setRuntimeData(Model $Model) {
@@ -400,7 +400,7 @@ protected function _setRuntimeData(Model $Model) {
  * Restores model data to the original data.
  * This solves issues with saveAssociated and validate = first.
  *
- * @param Model $model
+ * @param Model $Model Model using this behavior.
  * @return void
  */
 	public function afterValidate(Model $Model) {
@@ -479,7 +479,7 @@ public function afterSave(Model $Model, $created, $options = array()) {
  * Prepares the data to be saved for translated records.
  * Add blank fields, and populates data for multi-locale saves.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param array $data The sparse data that was provided.
  * @return array The fully populated data to save.
  */
@@ -569,7 +569,7 @@ public function translateModel(Model $Model) {
  * *Note* You should avoid binding translations that overlap existing model properties.
  * This can cause un-expected and un-desirable behavior.
  *
- * @param Model $Model instance of model
+ * @param Model $Model using this behavior of model
  * @param string|array $fields string with field or array(field1, field2=>AssocName, field3)
  * @param boolean $reset Leave true to have the fields only modified for the next operation.
  *   if false the field will be added for all future queries.
@@ -642,7 +642,7 @@ public function bindTranslation(Model $Model, $fields, $reset = true) {
 /**
  * Update runtime setting for a given field.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param string $field The field to update.
  * @return void
  */
@@ -664,7 +664,7 @@ protected function _removeField(Model $Model, $field) {
  * Unbind translation for fields, optionally unbinds hasMany association for
  * fake field
  *
- * @param Model $Model instance of model
+ * @param Model $Model using this behavior of model
  * @param string|array $fields string with field, or array(field1, field2=>AssocName, field3), or null for
  *    unbind all original translations
  * @return boolean

lib/Cake/Model/Behavior/TreeBehavior.php

@@ -58,7 +58,7 @@ class TreeBehavior extends ModelBehavior {
 /**
  * Initiate Tree behavior
  *
- * @param Model $Model instance of model
+ * @param Model $Model using this behavior of model
  * @param array $config array of configuration settings.
  * @return void
  */
@@ -84,7 +84,7 @@ public function setup(Model $Model, $config = array()) {
  * Overridden to transparently manage setting the lft and rght fields if and only if the parent field is included in the
  * parameters to be saved.
  *
- * @param Model $Model Model instance.
+ * @param Model $Model Model using this behavior.
  * @param boolean $created indicates whether the node just saved was created or updated
  * @param array $options Options passed from Model::save().
  * @return boolean true on success, false on failure
@@ -120,8 +120,8 @@ public function beforeFind(Model $Model, $query) {
  *
  * This is used to delete child nodes in the afterDelete.
  *
- * @param Model $Model Model instance
- * @param boolean $cascade
+ * @param Model $Model Model using this behavior.
+ * @param boolean $cascade If true records that depend on this record will also be deleted
  * @return boolean
  */
 	public function beforeDelete(Model $Model, $cascade = true) {
@@ -141,7 +141,7 @@ public function beforeDelete(Model $Model, $cascade = true) {
  *
  * Will delete the current node and all children using the deleteAll method and sync the table
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @return boolean true to continue, false to abort the delete
  */
 	public function afterDelete(Model $Model) {
@@ -172,8 +172,7 @@ public function afterDelete(Model $Model) {
  * parameters to be saved. For newly created nodes with NO parent the left and right field values are set directly by
  * this method bypassing the setParent logic.
  *
- * @since         1.2
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param array $options Options passed from Model::save().
  * @return boolean true to continue, false to abort the save
  * @see Model::save()
@@ -243,7 +242,7 @@ public function beforeSave(Model $Model, $options = array()) {
  * If the direct parameter is set to true, only the direct children are counted (based upon the parent_id field)
  * If false is passed for the id parameter, all top level nodes are counted, or all nodes are counted.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string|boolean $id The ID of the record to read or false to read all top level nodes
  * @param boolean $direct whether to count direct, or all, children
  * @return integer number of child nodes
@@ -284,7 +283,7 @@ public function childCount(Model $Model, $id = null, $direct = false) {
  * If the direct parameter is set to true, only the direct children are returned (based upon the parent_id field)
  * If false is passed for the id parameter, top level, or all (depending on direct parameter appropriate) are counted.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to read
  * @param boolean $direct whether to return only the direct, or all, children
  * @param string|array $fields Either a single string of a field name, or an array of field names
@@ -343,7 +342,7 @@ public function children(Model $Model, $id = null, $direct = false, $fields = nu
 /**
  * A convenience method for returning a hierarchical array used for HTML select boxes
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param string|array $conditions SQL conditions as a string or as an array('field' =>'value',...)
  * @param string $keyPath A string path to the key, i.e. "{n}.Post.id"
  * @param string $valuePath A string path to the value, i.e. "{n}.Post.title"
@@ -407,9 +406,9 @@ public function generateTreeList(Model $Model, $conditions = null, $keyPath = nu
  *
  * reads the parent id and returns this node
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to read
- * @param string|array $fields
+ * @param string|array $fields Fields to get
  * @param integer $recursive The number of levels deep to fetch associated records
  * @return array|boolean Array of data for the parent node
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/tree.html#TreeBehavior::getParentNode
@@ -440,7 +439,7 @@ public function getParentNode(Model $Model, $id = null, $fields = null, $recursi
 /**
  * Get the path to the given node
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to read
  * @param string|array $fields Either a single string of a field name, or an array of field names
  * @param integer $recursive The number of levels deep to fetch associated records
@@ -478,7 +477,7 @@ public function getPath(Model $Model, $id = null, $fields = null, $recursive = n
  *
  * If the node is the last child, or is a top level node with no subsequent node this method will return false
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to move
  * @param integer|boolean $number how many places to move the node or true to move to last position
  * @return boolean true on success, false on failure
@@ -536,7 +535,7 @@ public function moveDown(Model $Model, $id = null, $number = 1) {
  *
  * If the node is the first child, or is a top level node with no previous node this method will return false
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to move
  * @param integer|boolean $number how many places to move the node, or true to move to first position
  * @return boolean true on success, false on failure
@@ -598,7 +597,7 @@ public function moveUp(Model $Model, $id = null, $number = 1) {
  * 'parent' the values of the parent_id field will be used to populate the left and right fields. The missingParentAction
  * parameter only applies to "parent" mode and determines what to do if the parent field contains an id that is not present.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param string $mode parent or tree
  * @param string|integer $missingParentAction 'return' to do nothing and return, 'delete' to
  * delete, or the id of the parent to set as the parent_id
@@ -657,9 +656,9 @@ public function recover(Model $Model, $mode = 'parent', $missingParentAction = n
  *
  * Recursive helper function used by recover
  *
- * @param Model $Model
- * @param integer $counter
- * @param mixed $parentId
+ * @param Model $Model Model instance.
+ * @param integer $counter Counter
+ * @param mixed $parentId Parent record Id
  * @return integer $counter
  */
 	protected function _recoverByParentId(Model $Model, $counter = 1, $parentId = null) {
@@ -738,7 +737,7 @@ protected function _recoverByParentId(Model $Model, $counter = 1, $parentId = nu
  * - 'order' Direction to order either DESC or ASC (defaults to ASC)
  * - 'verify' Whether or not to verify the tree before reorder. defaults to true.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param array $options array of options to use in reordering.
  * @return boolean true on success, false on failure
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/tree.html#TreeBehavior::reorder
@@ -776,7 +775,7 @@ public function reorder(Model $Model, $options = array()) {
  * If the parameter delete is false, the node will become a new top level node. Otherwise the node will be deleted
  * after the children are reparented.
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @param integer|string $id The ID of the record to remove
  * @param boolean $delete whether to delete the node after reparenting children (if any)
  * @return boolean true on success, false on failure
@@ -846,7 +845,7 @@ public function removeFromTree(Model $Model, $id = null, $delete = false) {
  *
  * Returns true if the tree is valid otherwise an array of (type, incorrect left/right index, message)
  *
- * @param Model $Model Model instance
+ * @param Model $Model Model using this behavior
  * @return mixed true if the tree is valid or empty, otherwise an array of (error type [index, node],
  *  [incorrect left/right index,node id], message)
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/tree.html#TreeBehavior::verify
@@ -918,9 +917,9 @@ public function verify(Model $Model) {
  * of recovering a corrupted table, or creating new nodes. Otherwise it should always be false. In reality this
  * method could be private, since calling save with parent_id set also calls setParent
  *
- * @param Model $Model Model instance
- * @param integer|string $parentId
- * @param boolean $created
+ * @param Model $Model Model using this behavior
+ * @param integer|string $parentId Parent record Id
+ * @param boolean $created True if newly created record else false.
  * @return boolean true on success, false on failure
  */
 	protected function _setParent(Model $Model, $parentId = null, $created = false) {
@@ -988,11 +987,11 @@ protected function _setParent(Model $Model, $parentId = null, $created = false)
 /**
  * get the maximum index value in the table.
  *
- * @param Model $Model
- * @param string $scope
- * @param string $right
- * @param integer $recursive
- * @param boolean $created
+ * @param Model $Model Model Instance.
+ * @param string $scope Scoping conditions.
+ * @param string $right Right value
+ * @param integer $recursive Recursive find value.
+ * @param boolean $created Whether it's a new record.
  * @return integer
  */
 	protected function _getMax(Model $Model, $scope, $right, $recursive = -1, $created = false) {
@@ -1018,10 +1017,10 @@ protected function _getMax(Model $Model, $scope, $right, $recursive = -1, $creat
 /**
  * get the minimum index value in the table.
  *
- * @param Model $Model
- * @param string $scope
- * @param string $left
- * @param integer $recursive
+ * @param Model $Model Model instance.
+ * @param string $scope Scoping conditions.
+ * @param string $left Left value.
+ * @param integer $recursive Recurursive find value.
  * @return integer
  */
 	protected function _getMin(Model $Model, $scope, $left, $recursive = -1) {
@@ -1041,12 +1040,12 @@ protected function _getMin(Model $Model, $scope, $left, $recursive = -1) {
  *
  * Handles table sync operations, Taking account of the behavior scope.
  *
- * @param Model $Model
- * @param integer $shift
- * @param string $dir
- * @param array $conditions
- * @param boolean $created
- * @param string $field
+ * @param Model $Model Model instance.
+ * @param integer $shift Shift by.
+ * @param string $dir Direction.
+ * @param array $conditions Conditions.
+ * @param boolean $created Wheter it's a new record.
+ * @param string $field Field type.
  * @return void
  */
 	protected function _sync(Model $Model, $shift, $dir = '+', $conditions = array(), $created = false, $field = 'both') {