Merge pull request #3908 from markstory/3.0-api-docs

3.0 api docs

src/Console/Command/OrmCacheShell.php

@@ -32,7 +32,7 @@ class OrmCacheShell extends Shell {
 /**
  * Build metadata.
  *
- * @param $name string
+ * @param string $name The name of the table to build cache data for.
  * @return bool
  */
 	public function build($name = null) {
@@ -59,7 +59,7 @@ public function build($name = null) {
 /**
  * Clear metadata.
  *
- * @param $name string
+ * @param string $name The name of the table to clear cache data for.
  * @return bool
  */
 	public function clear($name = null) {

src/Console/Command/Task/ControllerTask.php

@@ -41,6 +41,7 @@ class ControllerTask extends BakeTask {
 /**
  * Execution method always used for tasks
  *
+ * @param string $name The name of the controller to bake.
  * @return void
  */
 	public function main($name = null) {
@@ -233,7 +234,6 @@ public function getHelpers() {
 /**
  * Outputs and gets the list of possible controllers from database
  *
- * @param string $useDbConfig Database configuration name
  * @return array Set of controllers
  */
 	public function listAll() {

src/Console/Command/Task/FixtureTask.php

@@ -86,6 +86,7 @@ public function getOptionParser() {
  * Execution method always used for tasks
  * Handles dispatching to interactive, named, or all processes.
  *
+ * @param string $name The name of the fixture to bake.
  * @return void
  */
 	public function main($name = null) {
@@ -309,7 +310,7 @@ protected function _values($values) {
 /**
  * Generate String representation of Records
  *
- * @param array $tableInfo Table schema array
+ * @param \Cake\Database\Schema\Table $table Table schema array
  * @param int $recordCount The number of records to generate.
  * @return array Array of records to use in the fixture.
  */

src/Console/Command/Task/ModelTask.php

@@ -71,6 +71,7 @@ class ModelTask extends BakeTask {
 /**
  * Execution method always used for tasks
  *
+ * @param string $name The name of the table to bake.
  * @return void
  */
 	public function main($name = null) {
@@ -155,7 +156,7 @@ public function getTableObject($className, $table) {
 /**
  * Get the array of associations to generate.
  *
- * @param \Cake\ORM\Table $table
+ * @param \Cake\ORM\Table $table The table to get associations for.
  * @return array
  */
 	public function getAssociations(Table $table) {
@@ -193,6 +194,10 @@ public function getAssociations(Table $table) {
  * Composer's class cache prevents us from loading the
  * newly generated class. Applying associations if we have a
  * generic table object means fields will be detected correctly.
+ *
+ * @param \Cake\ORM\Table $model The table to apply associations to.
+ * @param array $associations The associations to append.
+ * @return void
  */
 	public function applyAssociations($model, $associations) {
 		if (get_class($model) !== 'Cake\ORM\Table') {
@@ -432,7 +437,7 @@ public function getValidation($model) {
  *
  * @param string $fieldName Name of field to be validated.
  * @param array $metaData metadata for field
- * @param string $primaryKey
+ * @param string $primaryKey The primary key field
  * @return array Array of validation for the field.
  */
 	public function fieldValidation($fieldName, array $metaData, $primaryKey) {
@@ -491,7 +496,7 @@ public function fieldValidation($fieldName, array $metaData, $primaryKey) {
 /**
  * Get behaviors
  *
- * @param \Cake\ORM\Table $model
+ * @param \Cake\ORM\Table $model The model to generate behaviors for.
  * @return array Behaviors
  */
 	public function getBehaviors($model) {
@@ -522,7 +527,7 @@ public function getBehaviors($model) {
 /**
  * Get CounterCaches
  *
- * @param \Cake\ORM\Table $model
+ * @param \Cake\ORM\Table $model The table to get counter cache fields for.
  * @return array CounterCache configurations
  */
 	public function getCounterCache($model) {

src/Console/Command/Task/SimpleBakeTask.php

@@ -69,6 +69,7 @@ public function templateData() {
 /**
  * Execute method
  *
+ * @param string $name The name of the object to bake.
  * @return void
  */
 	public function main($name = null) {
@@ -85,7 +86,7 @@ public function main($name = null) {
 /**
  * Generate a class stub
  *
- * @param string $className The classname to generate.
+ * @param string $name The classname to generate.
  * @return void
  */
 	public function bake($name) {
@@ -101,6 +102,7 @@ public function bake($name) {
 /**
  * Generate a test case.
  *
+ * @param string $className The class to bake a test for.
  * @return void
  */
 	public function bakeTest($className) {

src/Console/Command/Task/ViewTask.php

@@ -96,6 +96,9 @@ public function initialize() {
 /**
  * Execution method always used for tasks
  *
+ * @param string $name The name of the controller to bake views for.
+ * @param string $template The template to bake with.
+ * @param string $action The action to bake with.
  * @return mixed
  */
 	public function main($name = null, $template = null, $action = null) {
@@ -266,7 +269,7 @@ protected function _loadController() {
  * Bake a view file for each of the supplied actions
  *
  * @param array $actions Array of actions to make files for.
- * @param array $vars
+ * @param array $vars The context for generating views.
  * @return void
  */
 	public function bakeActions(array $actions, $vars) {
@@ -412,7 +415,7 @@ public function getOptionParser() {
 /**
  * Returns associations for controllers models.
  *
- * @param Table $model
+ * @param Table $model The model to build associations for.
  * @return array associations
  */
 	protected function _associations(Table $model) {

src/Console/ConsoleIo.php

@@ -238,7 +238,7 @@ public function ask($prompt, $default = null) {
 /**
  * Change the output mode of the stdout stream
  *
- * @param int $mode
+ * @param int $mode The output mode.
  * @return void
  * @see \Cake\Console\ConsoleOutput::outputAs()
  */

src/Console/ConsoleOptionParser.php

@@ -458,9 +458,7 @@ public function subcommands() {
  * to parse the $argv
  *
  * @param array $argv Array of args (argv) to parse.
- * @param string $command The subcommand to use. If this parameter is a subcommand, that has a parser,
- *    That parser will be used to parse $argv instead.
- * @return Array [$params, $args]
+ * @return array [$params, $args]
  * @throws \Cake\Console\Error\ConsoleException When an invalid parameter is encountered.
  */
 	public function parse($argv) {

src/Console/Shell.php

@@ -172,8 +172,8 @@ public function __construct(ConsoleIo $io = null) {
 /**
  * Get/Set the io object for this shell.
  *
- * @param \Cake\Console\ConsoleIo $io
- * @return \Cake\Console\ConsoleIo
+ * @param \Cake\Console\ConsoleIo $io The ConsoleIo object to use.
+ * @return \Cake\Console\ConsoleIo The current ConsoleIo object.
  */
 	public function io(ConsoleIo $io = null) {
 		if ($io !== null) {
@@ -382,7 +382,7 @@ public function runCommand($argv, $autoMethod = false) {
 /**
  * Display the help in the correct format
  *
- * @param string $command
+ * @param string $command The command to get help for.
  * @return void
  */
 	protected function _displayHelp($command) {
@@ -413,8 +413,8 @@ public function getOptionParser() {
 /**
  * Overload get for lazy building of tasks
  *
- * @param string $name
- * @return Shell Object of Task
+ * @param string $name The task to get.
+ * @return \Cake\Console\Shell Object of Task
  */
 	public function __get($name) {
 		if (empty($this->{$name}) && in_array($name, $this->taskNames)) {

src/Database/Driver.php

@@ -79,7 +79,7 @@ public abstract function disconnect();
  * Returns correct connection resource or object that is internally used
  * If first argument is passed,
  *
- * @param null|\PDO instance $connection
+ * @param null|\PDO $connection The connection object
  * @return void
  */
 	public abstract function connection($connection = null);
@@ -94,7 +94,7 @@ public abstract function enabled();
 /**
  * Prepares a sql statement to be executed
  *
- * @param string|\Cake\Database\Query $query
+ * @param string|\Cake\Database\Query $query The query to convert into a statement.
  * @return \Cake\Database\StatementInterface
  */
 	public abstract function prepare($query);
@@ -132,7 +132,7 @@ public function supportsSavePoints() {
 /**
  * Returns a value in a safe representation to be used in a query string
  *
- * @param mixed $value
+ * @param mixed $value The value to quote.
  * @param string $type Type to be used for determining kind of quoting to perform
  * @return string
  */
@@ -175,7 +175,7 @@ public abstract function schemaDialect();
  * Quotes a database identifier (a column name, table name, etc..) to
  * be used safely in queries without the risk of using reserved words
  *
- * @param string $identifier
+ * @param string $identifier The identifier expression to quote.
  * @return string
  */
 	public abstract function quoteIdentifier($identifier);

src/Database/Driver/PDODriverTrait.php

@@ -52,7 +52,7 @@ protected function _connect(array $config) {
  * If first argument is passed, it will set internal conenction object or
  * result to the value passed
  *
- * @param null|\PDO instance $connection The PDO connection instance.
+ * @param null|\PDO $connection The PDO connection instance.
  * @return mixed connection object used internally
  */
 	public function connection($connection = null) {

src/Database/Expression/Comparison.php

@@ -68,7 +68,7 @@ public function __construct($field, $value, $type, $conjunction) {
 /**
  * Sets the field name
  *
- * @param string $field
+ * @param string $field The field to compare with.
  * @return void
  */
 	public function field($field) {
@@ -78,7 +78,7 @@ public function field($field) {
 /**
  * Sets the value
  *
- * @param mixed $value
+ * @param mixed $value The value to compare
  * @return void
  */
 	public function value($value) {
@@ -123,7 +123,7 @@ public function sql(ValueBinder $generator) {
  * Returns a template and an placeholder for the value after registering it
  * with the placeholder $generator
  *
- * @param ValueBinder $generator
+ * @param \Cake\Database\ValueBinder $generator The value binder to use.
  * @return array First position containing the template and the second a placeholder
  */
 	protected function _stringExpression($generator) {
@@ -141,9 +141,9 @@ protected function _stringExpression($generator) {
 /**
  * Registers a value in the placeholder generator and returns the generated placeholder
  *
- * @param mixed $value
- * @param ValueBinder $generator
- * @param string $type
+ * @param mixed $value The value to bind
+ * @param \Cake\Database\ValueBinder $generator The value binder to use
+ * @param string $type The type of $value
  * @return string generated placeholder
  */
 	protected function _bindValue($value, $generator, $type) {
@@ -157,7 +157,7 @@ protected function _bindValue($value, $generator, $type) {
  * $generator and separated by `,`
  *
  * @param array|\Traversable $value the value to flatten
- * @param ValueBinder $generator
+ * @param \Cake\Database\ValueBinder $generator The value binder to use
  * @param string|array $type the type to cast values to
  * @return string
  */

src/Database/Expression/FunctionExpression.php

@@ -67,7 +67,7 @@ public function __construct($name, $params = [], $types = []) {
  * Sets the name of the SQL function to be invoke in this expression,
  * if no value is passed it will return current name
  *
- * @param string $name
+ * @param string $name The name of the function
  * @return string
  */
 	public function name($name = null) {

src/Database/Expression/IdentifierExpression.php

@@ -37,13 +37,13 @@ class IdentifierExpression implements ExpressionInterface {
  * @param string $identifier The identifier this expression represents
  */
 	public function __construct($identifier) {
-		$this->setIdentifier($identifier);
+		$this->_identifier = $identifier;
 	}
 
 /**
  * Sets the identifier this expression represents
  *
- * @param string $identifier
+ * @param string $identifier The identifier
  * @return void
  */
 	public function setIdentifier($identifier) {
@@ -73,7 +73,7 @@ public function sql(ValueBinder $generator) {
  * This method is a no-op, this is a leaf type of expression,
  * hence there is nothing to traverse
  *
- * @param callable $callable
+ * @param callable $callable The callable to traverse with.
  * @return void
  */
 	public function traverse(callable $callable) {

src/Database/Expression/OrderByExpression.php

@@ -27,8 +27,8 @@ class OrderByExpression extends QueryExpression {
 /**
  * Constructor
  *
- * @param array $conditions
- * @param array $types
+ * @param array $conditions The sort columns
+ * @param array $types The types for each column.
  * @param string $conjunction The glue used to join conditions together.
  */
 	public function __construct($conditions = [], $types = [], $conjunction = '') {

src/Database/Expression/QueryExpression.php

@@ -60,7 +60,6 @@ class QueryExpression implements ExpressionInterface, Countable {
  * passed in $conditions.
  * @param string $conjunction the glue that will join all the string conditions at this
  * level of the expression tree. For example "AND", "OR", "XOR"...
- * @param TypeMap $typeMap contains default and call specific type mapping
  * @see QueryExpression::add() for more details on $conditions and $types
  */
 	public function __construct($conditions = [], $types = [], $conjunction = 'AND') {
@@ -373,7 +372,7 @@ public function sql(ValueBinder $generator) {
  *
  * Callback function receives as only argument an instance of a QueryExpression
  *
- * @param callable $callable
+ * @param callable $callable The callable to apply to all sub-expressions.
  * @return void
  */
 	public function traverse(callable $callable) {
@@ -396,7 +395,7 @@ public function traverse(callable $callable) {
  * passed by reference, this will enable you to change the key under which the
  * modified part is stored.
  *
- * @param callable $callable
+ * @param callable $callable The callable to apply to each part.
  * @return QueryExpression
  */
 	public function iterateParts(callable $callable) {
@@ -511,7 +510,7 @@ protected function _parseCondition($field, $value) {
  * to each value in the first argument.
  *
  * @param string $field database field to be used to bind values
- * @param array $values
+ * @param array $values The values to bind
  * @param string $type the type to be used to bind the values
  * @return array
  */