From 39b4032820f73b670695d9e419530fe8a41a25a3 Mon Sep 17 00:00:00 2001
From: Juan Basso <jrbasso@gmail.com>
Date: Sat, 30 Jul 2011 18:38:57 -0400
Subject: [PATCH] Fixed some API doc in model.

---
 lib/Cake/Model/Behavior/AclBehavior.php       |  6 +-
 .../Model/Behavior/ContainableBehavior.php    |  6 +-
 lib/Cake/Model/Behavior/TranslateBehavior.php |  4 +-
 lib/Cake/Model/Behavior/TreeBehavior.php      | 57 +++++++++--------
 lib/Cake/Model/BehaviorCollection.php         |  5 +-
 lib/Cake/Model/CakeSchema.php                 |  5 +-
 lib/Cake/Model/ConnectionManager.php          |  5 ++
 lib/Cake/Model/Datasource/CakeSession.php     |  9 ++-
 lib/Cake/Model/Datasource/DataSource.php      | 10 +--
 lib/Cake/Model/Datasource/Database/Mysql.php  |  8 ++-
 lib/Cake/Model/Datasource/Database/Oracle.php | 32 ++++++----
 .../Model/Datasource/Database/Postgres.php    | 12 ++--
 lib/Cake/Model/Datasource/Database/Sqlite.php | 15 ++---
 .../Model/Datasource/Database/Sqlserver.php   | 11 ++--
 lib/Cake/Model/Datasource/DboSource.php       | 62 +++++++++++--------
 lib/Cake/Model/Model.php                      | 43 ++++++-------
 lib/Cake/Model/ModelBehavior.php              | 32 +++++-----
 17 files changed, 182 insertions(+), 140 deletions(-)

diff --git a/lib/Cake/Model/Behavior/AclBehavior.php b/lib/Cake/Model/Behavior/AclBehavior.php
index 692f0d150..8d4f84c9f 100644
--- a/lib/Cake/Model/Behavior/AclBehavior.php
+++ b/lib/Cake/Model/Behavior/AclBehavior.php
@@ -38,7 +38,8 @@ class AclBehavior extends ModelBehavior {
 /**
  * Sets up the configuation for the model, and loads ACL models if they haven't been already
  *
- * @param mixed $config
+ * @param Model $model
+ * @param array $config
  * @return void
  */
 	public function setup($model, $config = array()) {
@@ -64,6 +65,7 @@ class AclBehavior extends ModelBehavior {
 /**
  * Retrieves the Aro/Aco node for this model
  *
+ * @param Model $model
  * @param mixed $ref
  * @param string $type Only needed when Acl is set up as 'both', specify 'Aro' or 'Aco' to get the correct node
  * @return array
@@ -86,6 +88,7 @@ class AclBehavior extends ModelBehavior {
 /**
  * Creates a new ARO/ACO node bound to this record
  *
+ * @param Model $model
  * @param boolean $created True if this is a new record
  * @return void
  */
@@ -116,6 +119,7 @@ class AclBehavior extends ModelBehavior {
 /**
  * Destroys the ARO/ACO node bound to the deleted record
  *
+ * @param Model $model
  * @return void
  */
 	public function afterDelete($model) {
diff --git a/lib/Cake/Model/Behavior/ContainableBehavior.php b/lib/Cake/Model/Behavior/ContainableBehavior.php
index 4892a7d93..749a0a7d9 100644
--- a/lib/Cake/Model/Behavior/ContainableBehavior.php
+++ b/lib/Cake/Model/Behavior/ContainableBehavior.php
@@ -58,8 +58,9 @@ class ContainableBehavior extends ModelBehavior {
  * - autoFields: (boolean, optional) auto-add needed fields to fetch requested
  *   bindings. DEFAULTS TO: true
  *
- * @param object $Model Model using the behavior
+ * @param Model $Model Model using the behavior
  * @param array $settings Settings to override for model.
+ * @return void
  */
 	public function setup($Model, $settings = array()) {
 		if (!isset($this->settings[$Model->alias])) {
@@ -226,9 +227,10 @@ class ContainableBehavior extends ModelBehavior {
  * Resets original associations on models that may have receive multiple,
  * subsequent unbindings.
  *
- * @param object $Model Model on which we are resetting
+ * @param Model $Model Model on which we are resetting
  * @param array $results Results of the find operation
  * @param bool $primary true if this is the primary model that issued the find operation, false otherwise
+ * @return void
  */
 	public function afterFind($Model, $results, $primary) {
 		if (!empty($Model->__backContainableAssociation)) {
diff --git a/lib/Cake/Model/Behavior/TranslateBehavior.php b/lib/Cake/Model/Behavior/TranslateBehavior.php
index e5eb703c3..8facac627 100644
--- a/lib/Cake/Model/Behavior/TranslateBehavior.php
+++ b/lib/Cake/Model/Behavior/TranslateBehavior.php
@@ -376,8 +376,8 @@ class TranslateBehavior extends ModelBehavior {
  * Bind translation for fields, optionally with hasMany association for
  * fake field
  *
- * @param object instance of model
- * @param mixed string with field or array(field1, field2=>AssocName, field3)
+ * @param Model $model instance of model
+ * @param string|array $fields string with field or array(field1, field2=>AssocName, field3)
  * @param boolean $reset
  * @return bool
  */
diff --git a/lib/Cake/Model/Behavior/TreeBehavior.php b/lib/Cake/Model/Behavior/TreeBehavior.php
index 2ee639cf1..945bdc461 100644
--- a/lib/Cake/Model/Behavior/TreeBehavior.php
+++ b/lib/Cake/Model/Behavior/TreeBehavior.php
@@ -76,7 +76,7 @@ class TreeBehavior extends ModelBehavior {
  * Overriden 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 AppModel $Model Model instance.
+ * @param Model $Model Model instance.
  * @param boolean $created indicates whether the node just saved was created or updated
  * @return boolean true on success, false on failure
  */
@@ -97,7 +97,8 @@ class TreeBehavior extends ModelBehavior {
  *
  * Will delete the current node and all children using the deleteAll method and sync the table
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
+ * @param boolean $cascade
  * @return boolean true to continue, false to abort the delete
  */
 	public function beforeDelete($Model, $cascade = true) {
@@ -129,7 +130,7 @@ class TreeBehavior extends ModelBehavior {
  * this method bypassing the setParent logic.
  *
  * @since         1.2
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @return boolean true to continue, false to abort the save
  */
 	public function beforeSave($Model) {
@@ -196,7 +197,7 @@ class TreeBehavior extends ModelBehavior {
  * 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 AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $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
@@ -237,7 +238,7 @@ class TreeBehavior extends ModelBehavior {
  * 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 AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $id The ID of the record to read
  * @param boolean $direct whether to return only the direct, or all, children
  * @param mixed $fields Either a single string of a field name, or an array of field names
@@ -296,7 +297,7 @@ class TreeBehavior extends ModelBehavior {
 /**
  * A convenience method for returning a hierarchical array used for HTML select boxes
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $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"
@@ -354,10 +355,11 @@ class TreeBehavior extends ModelBehavior {
  *
  * reads the parent id and returns this node
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $id The ID of the record to read
+ * @param string|array $fields
  * @param integer $recursive The number of levels deep to fetch associated records
- * @return array Array of data for the parent node
+ * @return array|boolean Array of data for the parent node
  * @link http://book.cakephp.org/view/1349/getparentnode
  */
 	public function getParentNode($Model, $id = null, $fields = null, $recursive = null) {
@@ -386,7 +388,7 @@ class TreeBehavior extends ModelBehavior {
 /**
  * Get the path to the given node
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $id The ID of the record to read
  * @param mixed $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
@@ -424,7 +426,7 @@ class TreeBehavior extends ModelBehavior {
  *
  * If the node is the last child, or is a top level node with no subsequent node this method will return false
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $id The ID of the record to move
  * @param int|bool $number how many places to move the node or true to move to last position
  * @return boolean true on success, false on failure
@@ -482,7 +484,7 @@ class TreeBehavior extends ModelBehavior {
  *
  * If the node is the first child, or is a top level node with no previous node this method will return false
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $id The ID of the record to move
  * @param int|bool $number how many places to move the node, or true to move to first position
  * @return boolean true on success, false on failure
@@ -545,7 +547,7 @@ class TreeBehavior extends ModelBehavior {
  * parameter only applies to "parent" mode and determines what to do if the parent field contains an id that is not present.
  *
  * @todo Could be written to be faster, *maybe*. Ideally using a subquery and putting all the logic burden on the DB.
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param string $mode parent or tree
  * @param mixed $missingParentAction 'return' to do nothing and return, 'delete' to
  * delete, or the id of the parent to set as the parent_id
@@ -626,7 +628,7 @@ class TreeBehavior extends ModelBehavior {
  * - '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 AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param array $options array of options to use in reordering.
  * @return boolean true on success, false on failure
  * @link http://book.cakephp.org/view/1355/reorder
@@ -665,7 +667,7 @@ class TreeBehavior extends ModelBehavior {
  * 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 AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $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
@@ -737,7 +739,7 @@ class TreeBehavior extends ModelBehavior {
  *
  * Returns true if the tree is valid otherwise an array of (type, incorrect left/right index, message)
  *
- * @param AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @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/view/1630/Verify
@@ -809,8 +811,9 @@ class TreeBehavior extends ModelBehavior {
  * 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 AppModel $Model Model instance
+ * @param Model $Model Model instance
  * @param mixed $parentId
+ * @param boolean $created
  * @return boolean true on success, false on failure
  */
 	protected function _setParent($Model, $parentId = null, $created = false) {
@@ -879,11 +882,12 @@ class TreeBehavior extends ModelBehavior {
 /**
  * get the maximum index value in the table.
  *
- * @param AppModel $Model
+ * @param Model $Model
  * @param string $scope
  * @param string $right
- * @return int
- * @access private
+ * @param integer $recursive
+ * @param boolean $created
+ * @return integer
  */
 	private function __getMax($Model, $scope, $right, $recursive = -1, $created = false) {
 		$db = ConnectionManager::getDataSource($Model->useDbConfig);
@@ -907,11 +911,11 @@ class TreeBehavior extends ModelBehavior {
 /**
  * get the minimum index value in the table.
  *
- * @param AppModel $Model
+ * @param Model $Model
  * @param string $scope
- * @param string $right
- * @return int
- * @access private
+ * @param string $left
+ * @param integer $recursive
+ * @return integer
  */
 	private function __getMin($Model, $scope, $left, $recursive = -1) {
 		$db = ConnectionManager::getDataSource($Model->useDbConfig);
@@ -929,12 +933,13 @@ class TreeBehavior extends ModelBehavior {
  *
  * Handles table sync operations, Taking account of the behavior scope.
  *
- * @param AppModel $Model
+ * @param Model $Model
  * @param integer $shift
- * @param string $direction
+ * @param string $dir
  * @param array $conditions
+ * @param boolean $created
  * @param string $field
- * @access private
+ * @return void
  */
 	private function __sync($Model, $shift, $dir = '+', $conditions = array(), $created = false, $field = 'both') {
 		$ModelRecursive = $Model->recursive;
diff --git a/lib/Cake/Model/BehaviorCollection.php b/lib/Cake/Model/BehaviorCollection.php
index f051fee04..9b17f2142 100644
--- a/lib/Cake/Model/BehaviorCollection.php
+++ b/lib/Cake/Model/BehaviorCollection.php
@@ -56,7 +56,8 @@ class BehaviorCollection extends ObjectCollection {
  * Attaches a model object and loads a list of behaviors
  *
  * @todo Make this method a constructor instead..
- * @access public
+ * @param string $modelName
+ * @param array $behaviors
  * @return void
  */
 	public function init($modelName, $behaviors = array()) {
@@ -72,6 +73,8 @@ class BehaviorCollection extends ObjectCollection {
 /**
  * Backwards compatible alias for load()
  *
+ * @param string $behavior
+ * @param array $config
  * @return void
  * @deprecated Replaced with load()
  */
diff --git a/lib/Cake/Model/CakeSchema.php b/lib/Cake/Model/CakeSchema.php
index 0a2b7978d..68e42f30e 100644
--- a/lib/Cake/Model/CakeSchema.php
+++ b/lib/Cake/Model/CakeSchema.php
@@ -135,7 +135,7 @@ class CakeSchema extends Object {
 /**
  * Before callback to be implemented in subclasses
  *
- * @param array $events schema object properties
+ * @param array $event schema object properties
  * @return boolean Should process continue
  */
 	public function before($event = array()) {
@@ -145,7 +145,8 @@ class CakeSchema extends Object {
 /**
  * After callback to be implemented in subclasses
  *
- * @param array $events schema object properties
+ * @param array $event schema object properties
+ * @return void
  */
 	public function after($event = array()) {
 	}
diff --git a/lib/Cake/Model/ConnectionManager.php b/lib/Cake/Model/ConnectionManager.php
index 0cd6eb1f3..b71695c7f 100644
--- a/lib/Cake/Model/ConnectionManager.php
+++ b/lib/Cake/Model/ConnectionManager.php
@@ -62,6 +62,7 @@ class ConnectionManager {
 /**
  * Loads connections configuration.
  *
+ * @return void
  */
 	private static function init() {
 		include_once APP . 'Config' . DS . 'database.php';
@@ -231,7 +232,9 @@ class ConnectionManager {
 /**
  * Gets a list of class and file names associated with the user-defined DataSource connections
  *
+ * @param string $name Connection name
  * @return void
+ * @throws MissingDatasourceConfigException
  */
 	protected static function _getConnectionObject($name) {
 		if (!empty(self::$config->{$name})) {
@@ -244,6 +247,7 @@ class ConnectionManager {
 /**
  * Returns the file, class name, and parent for the given driver.
  *
+ * @param array $config Array with connection configuration. Key 'datasource' is required
  * @return array An indexed array with: filename, classname, plugin and parent
  */
 	private static function _connectionData($config) {
@@ -260,6 +264,7 @@ class ConnectionManager {
 /**
  * Destructor.
  *
+ * @return void
  */
 	public static function shutdown() {
 		if (Configure::read('Session.defaults') == 'database' && function_exists('session_write_close')) {
diff --git a/lib/Cake/Model/Datasource/CakeSession.php b/lib/Cake/Model/Datasource/CakeSession.php
index 5807e4a41..7bdaafffd 100644
--- a/lib/Cake/Model/Datasource/CakeSession.php
+++ b/lib/Cake/Model/Datasource/CakeSession.php
@@ -133,6 +133,7 @@ class CakeSession {
  *
  * @param string $base The base path for the Session
  * @param boolean $start Should session be started right now
+ * @return void
  */
 	public static function init($base = null, $start = true) {
 		self::$time = time();
@@ -229,7 +230,7 @@ class CakeSession {
 /**
  * Returns the Session id
  *
- * @param id $name string
+ * @param string $id
  * @return string Session id
  */
 	public static function id($id = null) {
@@ -263,7 +264,7 @@ class CakeSession {
  *
  * @param array $old Set of old variables => values
  * @param array $new New set of variable => value
- * @access private
+ * @return void
  */
 	private static function __overwrite(&$old, $new) {
 		if (!empty($old)) {
@@ -508,6 +509,7 @@ class CakeSession {
 /**
  * Find the handler class and make sure it implements the correct interface.
  *
+ * @param string $handler
  * @return void
  */
 	protected static function _getHandler($handler) {
@@ -526,7 +528,8 @@ class CakeSession {
 /**
  * Get one of the prebaked default session configurations.
  *
- * @return void
+ * @param string $name
+ * @return boolean|array
  */
 	protected static function _defaultConfig($name) {
 		$defaults = array(
diff --git a/lib/Cake/Model/Datasource/DataSource.php b/lib/Cake/Model/Datasource/DataSource.php
index c0f797a2d..d1f429b7a 100644
--- a/lib/Cake/Model/Datasource/DataSource.php
+++ b/lib/Cake/Model/Datasource/DataSource.php
@@ -228,6 +228,7 @@ class DataSource extends Object {
  *
  * @param Model $model The model class having record(s) deleted
  * @param mixed $id Primary key of the model
+ * @return void
  */
 	public function delete(Model $model, $id = null) {
 		if ($id == null) {
@@ -238,7 +239,7 @@ class DataSource extends Object {
 /**
  * Returns the ID generated from the previous INSERT operation.
  *
- * @param unknown_type $source
+ * @param mixed $source
  * @return mixed Last ID key generated in previous INSERT
  */
 	public function lastInsertId($source = null) {
@@ -248,7 +249,7 @@ class DataSource extends Object {
 /**
  * Returns the number of rows returned by last operation.
  *
- * @param unknown_type $source
+ * @param mixed $source
  * @return integer Number of rows returned by last operation
  */
 	public function lastNumRows($source = null) {
@@ -258,7 +259,7 @@ class DataSource extends Object {
 /**
  * Returns the number of rows affected by last query.
  *
- * @param unknown_type $source
+ * @param mixed $source
  * @return integer Number of rows affected by last query.
  */
 	public function lastAffected($source = null) {
@@ -321,12 +322,11 @@ class DataSource extends Object {
  * @param string $query Query string needing replacements done.
  * @param array $data Array of data with values that will be inserted in placeholders.
  * @param string $association Name of association model being replaced
- * @param unknown_type $assocData
+ * @param array $assocData
  * @param Model $model Instance of the model to replace $__cakeID__$
  * @param Model $linkModel Instance of model to replace $__cakeForeignKey__$
  * @param array $stack
  * @return string String of query data with placeholders replaced.
- * @access public
  * @todo Remove and refactor $assocData, ensure uses of the method have the param removed too.
  */
 	public function insertQueryData($query, $data, $association, $assocData, Model $model, Model $linkModel, $stack) {
diff --git a/lib/Cake/Model/Datasource/Database/Mysql.php b/lib/Cake/Model/Datasource/Database/Mysql.php
index 87325a504..a120f16aa 100644
--- a/lib/Cake/Model/Datasource/Database/Mysql.php
+++ b/lib/Cake/Model/Datasource/Database/Mysql.php
@@ -177,6 +177,7 @@ class Mysql extends DboSource {
 /**
  * Returns an array of sources (tables) in the database.
  *
+ * @param mixed $data
  * @return array Array of tablenames in the database
  */
 	public function listSources($data = null) {
@@ -206,6 +207,7 @@ class Mysql extends DboSource {
  * Builds a map of the columns contained in a result
  *
  * @param PDOStatement $results
+ * @return void
  */
 	public function resultSet($results) {
 		$this->map = array();
@@ -287,7 +289,7 @@ class Mysql extends DboSource {
 /**
  * Returns an array of the fields in given table name.
  *
- * @param mixed $tableName Name of database table to inspect or model instance
+ * @param Model $model Name of database table to inspect or model instance
  * @return array Fields in table. Keys are name and type
  */
 	public function describe($model) {
@@ -416,6 +418,7 @@ class Mysql extends DboSource {
  * Sets the database encoding
  *
  * @param string $enc Database encoding
+ * @return boolean
  */
 	public function setEncoding($enc) {
 		return $this->_execute('SET NAMES ' . $enc) !== false;
@@ -458,6 +461,7 @@ class Mysql extends DboSource {
  * Generate a MySQL Alter Table syntax for the given Schema comparison
  *
  * @param array $compare Result of a CakeSchema::compare()
+ * @param string $table
  * @return array Array of alter statements to make.
  */
 	public function alterSchema($compare, $table = null) {
@@ -551,7 +555,7 @@ class Mysql extends DboSource {
  * Generate MySQL index alteration statements for a table.
  *
  * @param string $table Table to alter indexes for
- * @param array $new Indexes to add and drop
+ * @param array $indexes Indexes to add and drop
  * @return array Index alteration statements
  */
 	protected function _alterIndexes($table, $indexes) {
diff --git a/lib/Cake/Model/Datasource/Database/Oracle.php b/lib/Cake/Model/Datasource/Database/Oracle.php
index c07bbbdb9..4f3362dc3 100644
--- a/lib/Cake/Model/Datasource/Database/Oracle.php
+++ b/lib/Cake/Model/Datasource/Database/Oracle.php
@@ -196,6 +196,9 @@ class DboOracle extends DboSource {
 /**
  * Keeps track of the most recent Oracle error
  *
+ * @param mixed $source
+ * @param boolean $clear
+ * @return void
  */
 	protected function _setError($source = null, $clear = false) {
 		if ($source) {
@@ -473,7 +476,7 @@ class DboOracle extends DboSource {
 /**
  * Returns an array of the fields in given table name.
  *
- * @param object instance of a model to inspect
+ * @param Model $model instance of a model to inspect
  * @return array Fields in table. Keys are name and type
  */
 	public function describe($model) {
@@ -680,8 +683,9 @@ class DboOracle extends DboSource {
 /**
  * Generate a Oracle Alter Table syntax for the given Schema comparison
  *
- * @param unknown_type $schema
- * @return unknown
+ * @param mixed $compare
+ * @param mixed $table
+ * @return boolean|string
  */
 	public function alterSchema($compare, $table = null) {
 		if (!is_array($compare)) {
@@ -730,8 +734,8 @@ class DboOracle extends DboSource {
  * This method should quote Oracle identifiers. Well it doesn't.
  * It would break all scaffolding and all of Cake's default assumptions.
  *
- * @param unknown_type $var
- * @return unknown
+ * @param string $name
+ * @return string
  */
 	public function name($name) {
 		if (strpos($name, '.') !== false && strpos($name, '"') === false) {
@@ -838,6 +842,7 @@ class DboOracle extends DboSource {
  * Returns a quoted and escaped string of $data for use in an SQL statement.
  *
  * @param string $data String to be prepared for use in an SQL statement
+ * @param string $column
  * @return string Quoted and escaped
  */
 	public function value($data, $column = null) {
@@ -877,8 +882,8 @@ class DboOracle extends DboSource {
 /**
  * Returns the ID generated from the previous INSERT operation.
  *
- * @param string
- * @return integer
+ * @param string $source
+ * @return integer|boolean
  */
 	public function lastInsertId($source) {
 		$sequence = $this->_sequenceMap[$source];
@@ -962,15 +967,16 @@ class DboOracle extends DboSource {
  * Enter description here...
  *
  * @param Model $model
- * @param unknown_type $linkModel
+ * @param Model $linkModel
  * @param string $type Association type
- * @param unknown_type $association
- * @param unknown_type $assocData
- * @param unknown_type $queryData
- * @param unknown_type $external
- * @param unknown_type $resultSet
+ * @param string $association
+ * @param array $assocData
+ * @param array $queryData
+ * @param boolean $external
+ * @param array $resultSet
  * @param integer $recursive Number of levels of association
  * @param array $stack
+ * @return void
  */
 	public function queryAssociation($model, &$linkModel, $type, $association, $assocData, &$queryData, $external = false, &$resultSet, $recursive, $stack) {
 		if ($query = $this->generateAssociationQuery($model, $linkModel, $type, $association, $assocData, $queryData, $external, $resultSet)) {
diff --git a/lib/Cake/Model/Datasource/Database/Postgres.php b/lib/Cake/Model/Datasource/Database/Postgres.php
index 28dcfb894..09139c704 100644
--- a/lib/Cake/Model/Datasource/Database/Postgres.php
+++ b/lib/Cake/Model/Datasource/Database/Postgres.php
@@ -150,6 +150,7 @@ class Postgres extends DboSource {
 /**
  * Returns an array of tables in the database. If there are no tables, an error is raised and the application exits.
  *
+ * @param mixed $data
  * @return array Array of tablenames in the database
  */
 	public function listSources($data = null) {
@@ -181,7 +182,7 @@ class Postgres extends DboSource {
 /**
  * Returns an array of the fields in given table name.
  *
- * @param string $tableName Name of database table to inspect
+ * @param Model $model Name of database table to inspect
  * @return array Fields in table. Keys are name and type
  */
 	public function describe($model) {
@@ -335,6 +336,7 @@ class Postgres extends DboSource {
  * @param Model $model
  * @param string $alias Alias tablename
  * @param mixed $fields
+ * @param boolean $quote
  * @return array
  */
 	public function fields($model, $alias = null, $fields = array(), $quote = true) {
@@ -390,9 +392,8 @@ class Postgres extends DboSource {
 /**
  * Auxiliary function to quote matched `(Model.fields)` from a preg_replace_callback call
  *
- * @param string matched string
+ * @param string $match matched string
  * @return string quoted strig
- * @access private
  */
 	private function __quoteFunctionField($match) {
 		$prepend = '';
@@ -543,7 +544,7 @@ class Postgres extends DboSource {
  * Generate PostgreSQL index alteration statements for a table.
  *
  * @param string $table Table to alter indexes for
- * @param array $new Indexes to add and drop
+ * @param array $indexes Indexes to add and drop
  * @return array Index alteration statements
  */
 	protected function _alterIndexes($table, $indexes) {
@@ -679,7 +680,8 @@ class Postgres extends DboSource {
 /**
  * Enter description here...
  *
- * @param unknown_type $results
+ * @param array $results
+ * @return void
  */
 	public function resultSet(&$results) {
 		$this->map = array();
diff --git a/lib/Cake/Model/Datasource/Database/Sqlite.php b/lib/Cake/Model/Datasource/Database/Sqlite.php
index 0abb2dc83..dd2159d8e 100644
--- a/lib/Cake/Model/Datasource/Database/Sqlite.php
+++ b/lib/Cake/Model/Datasource/Database/Sqlite.php
@@ -105,9 +105,7 @@ class Sqlite extends DboSource {
 /**
  * Connects to the database using config['database'] as a filename.
  *
- * @param array $config Configuration array for connecting
- * @return mixed
- * @access public
+ * @return boolean
  */
 	public function connect() {
 		$config = $this->config;
@@ -134,8 +132,8 @@ class Sqlite extends DboSource {
 /**
  * Returns an array of tables in the database. If there are no tables, an error is raised and the application exits.
  *
+ * @param mixed $data
  * @return array Array of tablenames in the database
- * @access public
  */
 	public function listSources($data = null) {
 		$cache = parent::listSources();
@@ -161,9 +159,8 @@ class Sqlite extends DboSource {
 /**
  * Returns an array of the fields in given table name.
  *
- * @param string $tableName Name of database table to inspect
+ * @param Model $model
  * @return array Fields in table. Keys are name and type
- * @access public
  */
 	public function describe($model) {
 		$cache = parent::describe($model);
@@ -273,7 +270,7 @@ class Sqlite extends DboSource {
  * Generate ResultSet
  *
  * @param mixed $results
- * @access public
+ * @return void
  */
 	public function resultSet($results) {
 		$this->results = $results;
@@ -408,7 +405,7 @@ class Sqlite extends DboSource {
  * Sets the database encoding
  *
  * @param string $enc Database encoding
- * @access public
+ * @return boolean
  */
 	public function setEncoding($enc) {
 		if (!in_array($enc, array("UTF-8", "UTF-16", "UTF-16le", "UTF-16be"))) {
@@ -421,7 +418,6 @@ class Sqlite extends DboSource {
  * Gets the database encoding
  *
  * @return string The database encoding
- * @access public
  */
 	public function getEncoding() {
 		return $this->fetchRow('PRAGMA encoding');
@@ -433,7 +429,6 @@ class Sqlite extends DboSource {
  * @param array $indexes
  * @param string $table
  * @return string
- * @access public
  */
 	public function buildIndex($indexes, $table = null) {
 		$join = array();
diff --git a/lib/Cake/Model/Datasource/Database/Sqlserver.php b/lib/Cake/Model/Datasource/Database/Sqlserver.php
index 3d163dff9..fa4e561aa 100644
--- a/lib/Cake/Model/Datasource/Database/Sqlserver.php
+++ b/lib/Cake/Model/Datasource/Database/Sqlserver.php
@@ -262,7 +262,8 @@ class Sqlserver extends DboSource {
  *
  * @param Model $model
  * @param string $alias Alias tablename
- * @param mixed $fields
+ * @param array $fields
+ * @param boolean $quote
  * @return array
  */
 	public function fields($model, $alias = null, $fields = array(), $quote = true) {
@@ -327,7 +328,6 @@ class Sqlserver extends DboSource {
  * @param Model $model
  * @param array $fields
  * @param array $values
- * @param mixed $conditions
  * @return array
  */
 	public function create($model, $fields = null, $values = null) {
@@ -464,6 +464,7 @@ class Sqlserver extends DboSource {
  * Builds a map of the columns contained in a result
  *
  * @param PDOStatement $results
+ * @return void
  */
 	public function resultSet($results) {
 		$this->map = array();
@@ -589,8 +590,9 @@ class Sqlserver extends DboSource {
  * Returns an array of all result rows for a given SQL query.
  * Returns false if no rows matched.
  *
- * @param string $sql SQL statement
- * @param boolean $cache Enables returning/storing cached query results
+ * @param Model $model
+ * @param array $queryData
+ * @param integer $recursive
  * @return array Array of resultset rows, or false if no rows matched
  */
 	public function read($model, $queryData = array(), $recursive = null) {
@@ -630,6 +632,7 @@ class Sqlserver extends DboSource {
  * @param string $table
  * @param string $fields
  * @param array $values
+ * @return void
  */
 	public function insertMulti($table, $fields, $values) {
 		$primaryKey = $this->_getPrimaryKey($table);
diff --git a/lib/Cake/Model/Datasource/DboSource.php b/lib/Cake/Model/Datasource/DboSource.php
index e838c04c5..062f824dc 100644
--- a/lib/Cake/Model/Datasource/DboSource.php
+++ b/lib/Cake/Model/Datasource/DboSource.php
@@ -705,7 +705,7 @@ class DboSource extends DataSource {
 /**
  * Modifies $result array to place virtual fields in model entry where they belongs to
  *
- * @param array $resut Reference to the fetched row
+ * @param array $result Reference to the fetched row
  * @return void
  */
 	public function fetchVirtualField(&$result) {
@@ -913,6 +913,7 @@ class DboSource extends DataSource {
  * Log given SQL query.
  *
  * @param string $sql SQL statement
+ * @return void|boolean
  * @todo: Add hook to log errors instead of returning false
  */
 	public function logQuery($sql) {
@@ -938,6 +939,7 @@ class DboSource extends DataSource {
  * and execution time in microseconds. If the query fails, an error is output instead.
  *
  * @param string $sql Query to show information on.
+ * @return void
  */
 	public function showQuery($sql) {
 		$error = $this->error;
@@ -1166,13 +1168,14 @@ class DboSource extends DataSource {
  * @param Model $model Primary Model object
  * @param Model $linkModel Linked model that
  * @param string $type Association type, one of the model association types ie. hasMany
- * @param unknown_type $association
- * @param unknown_type $assocData
+ * @param string $association
+ * @param array $assocData
  * @param array $queryData
  * @param boolean $external Whether or not the association query is on an external datasource.
  * @param array $resultSet Existing results
  * @param integer $recursive Number of levels of association
  * @param array $stack
+ * @return mixed
  */
 	public function queryAssociation($model, &$linkModel, $type, $association, $assocData, &$queryData, $external = false, &$resultSet, $recursive, $stack) {
 		if ($query = $this->generateAssociationQuery($model, $linkModel, $type, $association, $assocData, $queryData, $external, $resultSet)) {
@@ -1372,14 +1375,14 @@ class DboSource extends DataSource {
 	}
 
 /**
- * Enter description here...
+ * Merge association of merge into data
  *
- * @param unknown_type $data
- * @param unknown_type $merge
- * @param unknown_type $association
- * @param unknown_type $type
+ * @param array $data
+ * @param array $merge
+ * @param string $association
+ * @param string $type
  * @param boolean $selfJoin
- * @access private
+ * @return void
  */
 	function __mergeAssociation(&$data, &$merge, $association, $type, $selfJoin = false) {
 		if (isset($merge[0]) && !isset($merge[0][$association])) {
@@ -1622,8 +1625,11 @@ class DboSource extends DataSource {
  * Returns a conditions array for the constraint between two models
  *
  * @param string $type Association type
- * @param object $model Model object
- * @param array $association Association array
+ * @param Model $model Model object
+ * @param string $linkModel
+ * @param string $alias
+ * @param array $assoc
+ * @param string $alias2
  * @return array Conditions array defining the constraint between $model and $association
  */
 	public function getConstraint($type, $model, $linkModel, $alias, $assoc, $alias2 = null) {
@@ -2078,8 +2084,8 @@ class DboSource extends DataSource {
 /**
  * Returns the ID generated from the previous INSERT operation.
  *
- * @param unknown_type $source
- * @return in
+ * @param mixed $source
+ * @return mixed
  */
 	public function lastInsertId($source = null) {
 		return $this->_connection->lastInsertId();
@@ -2120,9 +2126,9 @@ class DboSource extends DataSource {
 /**
  * Returns a key formatted like a string Model.fieldname(i.e. Post.title, or Country.name)
  *
- * @param unknown_type $model
- * @param unknown_type $key
- * @param unknown_type $assoc
+ * @param Model $model
+ * @param string $key
+ * @param string $assoc
  * @return string
  */
 	public function resolveKey($model, $key, $assoc = null) {
@@ -2549,9 +2555,8 @@ class DboSource extends DataSource {
 /**
  * Auxiliary function to quote matches `Model.fields` from a preg_replace_callback call
  *
- * @param string matched string
+ * @param string $match matched string
  * @return string quoted strig
- * @access private
  */
 	private function __quoteMatchedField($match) {
 		if (is_numeric($match[0])) {
@@ -2587,9 +2592,9 @@ class DboSource extends DataSource {
 /**
  * Returns an ORDER BY clause as a string.
  *
- * @param string $key Field reference, as a key (i.e. Post.title)
+ * @param array|string $keys Field reference, as a key (i.e. Post.title)
  * @param string $direction Direction (ASC or DESC)
- * @param object $model model reference (used to look for virtual field)
+ * @param Model $model model reference (used to look for virtual field)
  * @return string ORDER BY clause
  */
 	public function order($keys, $direction = 'ASC', $model = null) {
@@ -2656,7 +2661,8 @@ class DboSource extends DataSource {
  * Create a GROUP BY SQL clause
  *
  * @param string $group Group By Condition
- * @return mixed string condition or null
+ * @param Model $model
+ * @return null|string string condition or null
  */
 	public function group($group, $model = null) {
 		if ($group) {
@@ -2686,7 +2692,7 @@ class DboSource extends DataSource {
 /**
  * Checks if the specified table contains any record matching specified SQL
  *
- * @param Model $model Model to search
+ * @param Model $Model Model to search
  * @param string $sql SQL WHERE clause (condition only, not the "WHERE" part)
  * @return boolean True if the table has a matching record, else false
  */
@@ -2769,7 +2775,8 @@ class DboSource extends DataSource {
  * Translates between PHP boolean values and Database (faked) boolean values
  *
  * @param mixed $data Value to be translated
- * @return int Converted boolean value
+ * @param boolean $quote
+ * @return string|boolean Converted boolean value
  */
 	public function boolean($data, $quote = false) {
 		if ($quote) {
@@ -2784,6 +2791,7 @@ class DboSource extends DataSource {
  * @param string $table
  * @param string $fields
  * @param array $values
+ * @return boolean
  */
 	public function insertMulti($table, $fields, $values) {
 		$table = $this->fullTableName($table);
@@ -2863,9 +2871,10 @@ class DboSource extends DataSource {
 	}
 
 /**
- * Generate a alter syntax from	 CakeSchema::compare()
+ * Generate a alter syntax from	CakeSchema::compare()
  *
- * @param unknown_type $schema
+ * @param mixed $compare
+ * @param string $table
  * @return boolean
  */
 	public function alterSchema($compare, $table = null) {
@@ -3011,8 +3020,7 @@ class DboSource extends DataSource {
 /**
  * Read additional table parameters
  *
- * @param array $parameters
- * @param string $table
+ * @param string $name
  * @return array
  */
 	public function readTableParameters($name) {
diff --git a/lib/Cake/Model/Model.php b/lib/Cake/Model/Model.php
index e980fb4cd..683935c95 100644
--- a/lib/Cake/Model/Model.php
+++ b/lib/Cake/Model/Model.php
@@ -1082,7 +1082,7 @@ class Model extends Object {
 /**
  * Returns true if the supplied field is a model Virtual Field
  *
- * @param mixed $name Name of field to look for
+ * @param string $field Name of field to look for
  * @return boolean indicating whether the field exists as a model virtual field.
  */
 	public function isVirtualField($field) {
@@ -1104,7 +1104,7 @@ class Model extends Object {
 /**
  * Returns the expression for a model virtual field
  *
- * @param mixed $name Name of field to look for
+ * @param string $field Name of field to look for
  * @return mixed If $field is string expression bound to virtual field $field
  *    If $field is null, returns an array of all model virtual fields
  *    or false if none $field exist.
@@ -1435,7 +1435,8 @@ class Model extends Object {
  *
  * @param array $joined Data to save
  * @param mixed $id ID of record in this model
- * @access private
+ * @param DataSource $db
+ * @return void
  */
 	private function __saveMulti($joined, $id, $db) {
 		foreach ($joined as $assoc => $data) {
@@ -1868,11 +1869,10 @@ class Model extends Object {
  * - fieldList: Equivalent to the $fieldList parameter in Model::save()
  *
  * @param array $data Record data to validate. This should be an array indexed by association name.
- * @param array Options to use when validating record data (see above), See also $options of validates().
- * @return mixed If atomic: True on success, or false on failure.
+ * @param array $options Options to use when validating record data (see above), See also $options of validates().
+ * @return array|boolean If atomic: True on success, or false on failure.
  *    Otherwise: array similar to the $data array passed, but values are set to true/false
  *    depending on whether each record validated successfully.
- * @access public
  */
 	public function validateAssociated($data, $options = array()) {
 		$options = array_merge(array('atomic' => true), $options);
@@ -2097,8 +2097,8 @@ class Model extends Object {
 /**
  * Collects foreign keys from associations.
  *
+ * @param string $type
  * @return array
- * @access private
  */
 	private function __collectForeignKeys($type = 'belongsTo') {
 		$result = array();
@@ -2280,7 +2280,7 @@ class Model extends Object {
  *
  * @param string $state Either "before" or "after"
  * @param array $query
- * @param array $data
+ * @param array $results
  * @return array
  * @see Model::find()
  */
@@ -2301,7 +2301,7 @@ class Model extends Object {
  *
  * @param string $state Either "before" or "after"
  * @param array $query
- * @param array $data
+ * @param array $results
  * @return int The number of records found, or false
  * @see Model::find()
  */
@@ -2332,7 +2332,7 @@ class Model extends Object {
  *
  * @param string $state Either "before" or "after"
  * @param array $query
- * @param array $data
+ * @param array $results
  * @return array Key/value pairs of primary keys/display field values of all records found
  * @see Model::find()
  */
@@ -2491,7 +2491,7 @@ class Model extends Object {
 /**
  * Passes query results through model and behavior afterFilter() methods.
  *
- * @param array Results to filter
+ * @param array $results Results to filter
  * @param boolean $primary If this is the primary model results (results from model where the find operation was performed)
  * @return array Set of filtered results
  */
@@ -2582,7 +2582,6 @@ class Model extends Object {
  *
  * @param string $sql SQL statement
  * @return array Resultset
- * @access public
  * @link http://book.cakephp.org/view/1027/query
  */
 	public function query() {
@@ -2813,6 +2812,7 @@ class Model extends Object {
  * @param string $field The name of the field to invalidate
  * @param mixed $value Name of validation rule that was not failed, or validation message to
  *    be returned. If no validation key is provided, defaults to true.
+ * @return void
  */
 	public function invalidate($field, $value = true) {
 		if (!is_array($this->validationErrors)) {
@@ -2912,7 +2912,8 @@ class Model extends Object {
 /**
  * Sets the ID of the last record this model inserted
  *
- * @param mixed Last inserted ID
+ * @param mixed $id Last inserted ID
+ * @return void
  */
 	public function setInsertID($id) {
 		$this->__insertID = $id;
@@ -3033,8 +3034,7 @@ class Model extends Object {
  * Gets the name and fields to be used by a join model.  This allows specifying join fields
  * in the association definition.
  *
- * @param object $model The model to be joined
- * @param mixed $with The 'with' key of the model association
+ * @param string|array $assoc The model to be joined
  * @param array $keys Any join keys which must be merged with the keys queried
  * @return array
  */
@@ -3084,8 +3084,8 @@ class Model extends Object {
  * Called before each save operation, after validation. Return a non-true result
  * to halt the save.
  *
+ * @param array $options
  * @return boolean True if the operation should continue, false if it should abort
- * @access public
  * @link http://book.cakephp.org/view/1048/Callback-Methods#beforeSave-1052
  */
 	public function beforeSave($options = array()) {
@@ -3096,7 +3096,7 @@ class Model extends Object {
  * Called after each successful save operation.
  *
  * @param boolean $created True if this save created a new record
- * @access public
+ * @return void
  * @link http://book.cakephp.org/view/1048/Callback-Methods#afterSave-1053
  */
 	public function afterSave($created) {
@@ -3107,7 +3107,6 @@ class Model extends Object {
  *
  * @param boolean $cascade If true records that depend on this record will also be deleted
  * @return boolean True if the operation should continue, false if it should abort
- * @access public
  * @link http://book.cakephp.org/view/1048/Callback-Methods#beforeDelete-1054
  */
 	public function beforeDelete($cascade = true) {
@@ -3117,7 +3116,7 @@ class Model extends Object {
 /**
  * Called after every deletion operation.
  *
- * @access public
+ * @return void
  * @link http://book.cakephp.org/view/1048/Callback-Methods#afterDelete-1055
  */
 	public function afterDelete() {
@@ -3127,9 +3126,8 @@ class Model extends Object {
  * Called during validation operations, before validation. Please note that custom
  * validation rules can be defined in $validate.
  *
+ * @param array $options Options passed from model::save(), see $options of model::save().
  * @return boolean True if validate operation should continue, false to abort
- * @param $options array Options passed from model::save(), see $options of model::save().
- * @access public
  * @link http://book.cakephp.org/view/1048/Callback-Methods#beforeValidate-1051
  */
 	public function beforeValidate($options = array()) {
@@ -3139,7 +3137,7 @@ class Model extends Object {
 /**
  * Called when a DataSource-level error occurs.
  *
- * @access public
+ * @return void
  * @link http://book.cakephp.org/view/1048/Callback-Methods#onError-1056
  */
 	public function onError() {
@@ -3151,7 +3149,6 @@ class Model extends Object {
  * @param string $type If null this deletes cached views if Cache.check is true
  *     Will be used to allow deleting query cache also
  * @return boolean true on delete
- * @access protected
  * @todo
  */
 	protected function _clearCache($type = null) {
diff --git a/lib/Cake/Model/ModelBehavior.php b/lib/Cake/Model/ModelBehavior.php
index be0cc0f67..4b4210b41 100644
--- a/lib/Cake/Model/ModelBehavior.php
+++ b/lib/Cake/Model/ModelBehavior.php
@@ -88,8 +88,9 @@ class ModelBehavior extends Object {
 /**
  * Setup this behavior with the specified configuration settings.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param array $config Configuration settings for $model
+ * @return void
  */
 	public function setup($model, $config = array()) { }
 
@@ -97,7 +98,8 @@ class ModelBehavior extends Object {
  * Clean up any initialization this behavior has done on a model.  Called when a behavior is dynamically
  * detached from a model using Model::detach().
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
+ * @return void
  * @see BehaviorCollection::detach()
  */
 	public function cleanup($model) {
@@ -111,9 +113,9 @@ class ModelBehavior extends Object {
  * By returning null/false you can abort a find.  By returning an array you can modify/replace the query
  * that is going to be run.
  *
- * @param object $model Model using this behavior
- * @param array $queryData Data used to execute this query, i.e. conditions, order, etc.
- * @return mixed False or null will abort the operation. You can return an array to replace the
+ * @param Model $model Model using this behavior
+ * @param array $query Data used to execute this query, i.e. conditions, order, etc.
+ * @return boolean|array False or null will abort the operation. You can return an array to replace the
  *   $query that will be eventually run.
  */
 	public function beforeFind($model, $query) {
@@ -123,7 +125,7 @@ class ModelBehavior extends Object {
 /**
  * After find callback. Can be used to modify any results returned by find.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param mixed $results The results of the find operation
  * @param boolean $primary Whether this model is being queried directly (vs. being queried as an association)
  * @return mixed An array value will replace the value of $results - any other value will be ignored.
@@ -135,7 +137,7 @@ class ModelBehavior extends Object {
  * add behavior validation rules into a models validate array.  Returning false
  * will allow you to make the validation fail.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @return mixed False or null will abort the operation. Any other result will continue.
  * @access public
  */
@@ -147,7 +149,7 @@ class ModelBehavior extends Object {
  * beforeSave is called before a model is saved.  Returning false from a beforeSave callback
  * will abort the save operation.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @return mixed False if the operation should abort. Any other result will continue.
  */
 	public function beforeSave($model) {
@@ -157,8 +159,9 @@ class ModelBehavior extends Object {
 /**
  * afterSave is called after a model is saved.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param boolean $created True if this save created a new record
+ * @return boolean
  */
 	public function afterSave($model, $created) {
 		return true;
@@ -168,10 +171,9 @@ class ModelBehavior extends Object {
  * Before delete is called before any delete occurs on the attached model, but after the model's
  * beforeDelete is called.  Returning false from a beforeDelete will abort the delete.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param boolean $cascade If true records that depend on this record will also be deleted
  * @return mixed False if the operation should abort. Any other result will continue.
- * @access public
  */
 	public function beforeDelete($model, $cascade = true) {
 		return true;
@@ -180,15 +182,17 @@ class ModelBehavior extends Object {
 /**
  * After delete is called after any delete occurs on the attached model.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
+ * @return void
  */
 	public function afterDelete($model) { }
 
 /**
  * DataSource error callback
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param string $error Error generated in DataSource
+ * @return void
  */
 	public function onError($model, $error) { }
 
@@ -198,7 +202,7 @@ class ModelBehavior extends Object {
  * that it only modifies the whitelist for the current save operation.  Also make sure
  * you explicitly set the value of the field which you are allowing.
  *
- * @param object $model Model using this behavior
+ * @param Model $model Model using this behavior
  * @param string $field Field to be added to $model's whitelist
  * @return void
  */