Merge pull request #3661 from cakephp/api-docs

Api docs

lib/Cake/Controller/Component/Acl/PhpAcl.php

@@ -407,9 +407,9 @@ class PhpAro {
 /**
  * Constructor
  *
- * @param array $aro
- * @param array $map
- * @param array $aliases
+ * @param array $aro The aro data
+ * @param array $map The identifier mappings
+ * @param array $aliases The aliases to map.
  */
 	public function __construct(array $aro = array(), array $map = array(), array $aliases = array()) {
 		if (!empty($map)) {

lib/Cake/Model/Datasource/Database/Mysql.php

@@ -212,7 +212,7 @@ class Mysql extends DboSource {
 /**
  * Returns an array of sources (tables) in the database.
  *
- * @param mixed $data
+ * @param mixed $data List of tables.
  * @return array Array of table names in the database
  */
 	public function listSources($data = null) {
@@ -240,7 +240,7 @@ class Mysql extends DboSource {
 /**
  * Builds a map of the columns contained in a result
  *
- * @param PDOStatement $results
+ * @param PDOStatement $results The results to format.
  * @return void
  */
 	public function resultSet($results) {
@@ -374,10 +374,10 @@ class Mysql extends DboSource {
 /**
  * Generates and executes an SQL UPDATE statement for given model, fields, and values.
  *
- * @param Model $model
- * @param array $fields
- * @param array $values
- * @param mixed $conditions
+ * @param Model $model The model to update.
+ * @param array $fields The fields to update.
+ * @param array $values The values to set.
+ * @param mixed $conditions The conditions to use.
  * @return array
  */
 	public function update(Model $model, $fields = array(), $values = null, $conditions = null) {
@@ -418,8 +418,8 @@ class Mysql extends DboSource {
 /**
  * Generates and executes an SQL DELETE statement for given id/conditions on given model.
  *
- * @param Model $model
- * @param mixed $conditions
+ * @param Model $model The model to delete from.
+ * @param mixed $conditions The conditions to use.
  * @return boolean Success
  */
 	public function delete(Model $model, $conditions = null) {
@@ -516,7 +516,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
+ * @param string $table The table name.
  * @return array Array of alter statements to make.
  */
 	public function alterSchema($compare, $table = null) {

lib/Cake/Model/Datasource/Database/Postgres.php

@@ -158,7 +158,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
+ * @param mixed $data The sources to list.
  * @return array Array of table names in the database
  */
 	public function listSources($data = null) {
@@ -361,7 +361,7 @@ class Postgres extends DboSource {
 /**
  * Prepares field names to be quoted by parent
  *
- * @param string $data
+ * @param string $data The name to format.
  * @return string SQL field
  */
 	public function name($data) {
@@ -374,10 +374,10 @@ class Postgres extends DboSource {
 /**
  * Generates the fields list of an SQL query.
  *
- * @param Model $model
- * @param string $alias Alias table name
- * @param mixed $fields
- * @param boolean $quote
+ * @param Model $model The model to get fields for.
+ * @param string $alias Alias table name.
+ * @param mixed $fields The list of fields to get.
+ * @param boolean $quote Whether or not to quote identifiers.
  * @return array
  */
 	public function fields(Model $model, $alias = null, $fields = array(), $quote = true) {
@@ -731,7 +731,7 @@ class Postgres extends DboSource {
 /**
  * resultSet method
  *
- * @param array $results
+ * @param array &$results The results
  * @return void
  */
 	public function resultSet(&$results) {
@@ -886,8 +886,8 @@ class Postgres extends DboSource {
 /**
  * Format indexes for create table
  *
- * @param array $indexes
- * @param string $table
+ * @param array $indexes The index to build
+ * @param string $table The table name.
  * @return string
  */
 	public function buildIndex($indexes, $table = null) {
@@ -918,8 +918,8 @@ class Postgres extends DboSource {
 /**
  * Overrides DboSource::renderStatement to handle schema generation with Postgres-style indexes
  *
- * @param string $type
- * @param array $data
+ * @param string $type The query type.
+ * @param array $data The array of data to render.
  * @return string
  */
 	public function renderStatement($type, $data) {

lib/Cake/Model/Datasource/Database/Sqlserver.php

@@ -166,7 +166,7 @@ class Sqlserver extends DboSource {
 /**
  * Returns an array of sources (tables) in the database.
  *
- * @param mixed $data
+ * @param mixed $data The names
  * @return array Array of table names in the database
  */
 	public function listSources($data = null) {
@@ -269,10 +269,10 @@ class Sqlserver extends DboSource {
 /**
  * Generates the fields list of an SQL query.
  *
- * @param Model $model
+ * @param Model $model The model to get fields for.
  * @param string $alias Alias table name
- * @param array $fields
- * @param boolean $quote
+ * @param array $fields The fields so far.
+ * @param boolean $quote Whether or not to quote identfiers.
  * @return array
  */
 	public function fields(Model $model, $alias = null, $fields = array(), $quote = true) {
@@ -338,9 +338,9 @@ class Sqlserver extends DboSource {
  * Removes Identity (primary key) column from update data before returning to parent, if
  * value is empty.
  *
- * @param Model $model
- * @param array $fields
- * @param array $values
+ * @param Model $model The model to insert into.
+ * @param array $fields The fields to set.
+ * @param array $values The values to set.
  * @return array
  */
 	public function create(Model $model, $fields = null, $values = null) {
@@ -367,10 +367,10 @@ class Sqlserver extends DboSource {
  * Generates and executes an SQL UPDATE statement for given model, fields, and values.
  * Removes Identity (primary key) column from update data before returning to parent.
  *
- * @param Model $model
- * @param array $fields
- * @param array $values
- * @param mixed $conditions
+ * @param Model $model The model to update.
+ * @param array $fields The fields to set.
+ * @param array $values The values to set.
+ * @param mixed $conditions The conditions to use.
  * @return array
  */
 	public function update(Model $model, $fields = array(), $values = null, $conditions = null) {
@@ -482,7 +482,7 @@ class Sqlserver extends DboSource {
 /**
  * Builds a map of the columns contained in a result
  *
- * @param PDOStatement $results
+ * @param PDOStatement $results The result to modify.
  * @return void
  */
 	public function resultSet($results) {
@@ -608,9 +608,9 @@ class Sqlserver extends DboSource {
  * Returns an array of all result rows for a given SQL query.
  * Returns false if no rows matched.
  *
- * @param Model $model
- * @param array $queryData
- * @param integer $recursive
+ * @param Model $model The model to read from
+ * @param array $queryData The query data
+ * @param integer $recursive How many layers to go.
  * @return array|false Array of resultset rows, or false if no rows matched
  */
 	public function read(Model $model, $queryData = array(), $recursive = null) {
@@ -647,9 +647,9 @@ class Sqlserver extends DboSource {
 /**
  * Inserts multiple values into a table
  *
- * @param string $table
- * @param string $fields
- * @param array $values
+ * @param string $table The table to insert into.
+ * @param string $fields The fields to set.
+ * @param array $values The values to set.
  * @return void
  */
 	public function insertMulti($table, $fields, $values) {
@@ -699,8 +699,8 @@ class Sqlserver extends DboSource {
 /**
  * Format indexes for create table
  *
- * @param array $indexes
- * @param string $table
+ * @param array $indexes The indexes to build
+ * @param string $table The table to make indexes for.
  * @return string
  */
 	public function buildIndex($indexes, $table = null) {
@@ -744,7 +744,7 @@ class Sqlserver extends DboSource {
  * Returns number of affected rows in previous database operation. If no previous operation exists,
  * this returns false.
  *
- * @param mixed $source
+ * @param mixed $source Unused
  * @return integer Number of affected rows
  */
 	public function lastAffected($source = null) {

lib/Cake/TestSuite/CakeTestCase.php

@@ -373,7 +373,7 @@ abstract class CakeTestCase extends PHPUnit_Framework_TestCase {
  *
  * @param string $string An HTML/XHTML/XML string
  * @param array $expected An array, see above
- * @param string $message SimpleTest failure output string
+ * @param string $fullDebug Whether or not more verbose output should be used.
  * @return boolean
  */
 	public function assertTags($string, $expected, $fullDebug = false) {

lib/Cake/TestSuite/CakeTestSuiteCommand.php

@@ -35,7 +35,7 @@ class CakeTestSuiteCommand extends PHPUnit_TextUI_Command {
 /**
  * Construct method
  *
- * @param mixed $loader
+ * @param mixed $loader The loader instance to use.
  * @param array $params list of options to be used for this run
  * @throws MissingTestLoaderException When a loader class could not be found.
  */
@@ -55,8 +55,8 @@ class CakeTestSuiteCommand extends PHPUnit_TextUI_Command {
 /**
  * Ugly hack to get around PHPUnit having a hard coded class name for the Runner. :(
  *
- * @param array   $argv
- * @param boolean $exit
+ * @param array $argv The command arguments
+ * @param boolean $exit The exit mode.
  * @return void
  */
 	public function run(array $argv, $exit = true) {
@@ -131,7 +131,7 @@ class CakeTestSuiteCommand extends PHPUnit_TextUI_Command {
 /**
  * Handles output flag used to change printing on webrunner.
  *
- * @param string $reporter
+ * @param string $reporter The reporter class to use.
  * @return void
  */
 	public function handleReporter($reporter) {

lib/Cake/TestSuite/Coverage/BaseCoverageReport.php

@@ -134,8 +134,8 @@ abstract class BaseCoverageReport {
  * 3.5 uses -1 for uncovered, and -2 for dead.
  * 3.6 uses array() for uncovered and null for dead.
  *
- * @param array $fileLines
- * @param array $coverageData
+ * @param array $fileLines The lines in the file.
+ * @param array $coverageData The raw coverage data.
  * @return array Array of covered, total lines.
  */
 	protected function _calculateCoveredLines($fileLines, $coverageData) {

lib/Cake/TestSuite/Coverage/HtmlCoverageReport.php

@@ -127,7 +127,7 @@ HTML;
 /**
  * Guess the class name the test was for based on the test case filename.
  *
- * @param ReflectionClass $testReflection.
+ * @param ReflectionClass $testReflection The class to reflect
  * @return string Possible test subject name.
  */
 	protected function _guessSubjectName($testReflection) {
@@ -143,10 +143,10 @@ HTML;
 /**
  * Renders the HTML for a single line in the HTML diff.
  *
- * @param string $line
- * @param integer $linenumber
- * @param string $class
- * @param array $coveringTests
+ * @param string $line The line content.
+ * @param integer $linenumber The line number
+ * @param string $class The classname to use.
+ * @param array $coveringTests The tests covering the line.
  * @return string
  */
 	protected function _paintLine($line, $linenumber, $class, $coveringTests) {
@@ -195,8 +195,8 @@ HTML;
 /**
  * Generate an HTML snippet for coverage headers
  *
- * @param string $filename
- * @param string $percent
+ * @param string $filename The file name being covered
+ * @param string $percent The percentage covered
  * @return string
  */
 	public function coverageHeader($filename, $percent) {

lib/Cake/TestSuite/Reporter/CakeBaseReporter.php

@@ -121,7 +121,7 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * Print result
  *
- * @param PHPUnit_Framework_TestResult $result
+ * @param PHPUnit_Framework_TestResult $result The result object
  * @return void
  */
 	public function printResult(PHPUnit_Framework_TestResult $result) {
@@ -131,7 +131,7 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * Paint result
  *
- * @param PHPUnit_Framework_TestResult $result
+ * @param PHPUnit_Framework_TestResult $result The result object
  * @return void
  */
 	public function paintResult(PHPUnit_Framework_TestResult $result) {
@@ -141,9 +141,9 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * An error occurred.
  *
- * @param  PHPUnit_Framework_Test $test
- * @param  Exception              $e
- * @param  float                  $time
+ * @param  PHPUnit_Framework_Test $test The test to add an error for.
+ * @param  Exception $e The exception object to add.
+ * @param  float $time The current time.
  * @return void
  */
 	public function addError(PHPUnit_Framework_Test $test, Exception $e, $time) {
@@ -153,9 +153,9 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * A failure occurred.
  *
- * @param  PHPUnit_Framework_Test $test
- * @param  PHPUnit_Framework_AssertionFailedError $e
- * @param  float $time
+ * @param  PHPUnit_Framework_Test $test The test that failed
+ * @param  PHPUnit_Framework_AssertionFailedError $e The assertion that failed.
+ * @param  float $time The current time.
  * @return void
  */
 	public function addFailure(PHPUnit_Framework_Test $test, PHPUnit_Framework_AssertionFailedError $e, $time) {
@@ -165,9 +165,9 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * Incomplete test.
  *
- * @param  PHPUnit_Framework_Test $test
- * @param  Exception $e
- * @param  float $time
+ * @param  PHPUnit_Framework_Test $test The test that was incomplete.
+ * @param  Exception $e The incomplete exception
+ * @param  float $time The current time.
  * @return void
  */
 	public function addIncompleteTest(PHPUnit_Framework_Test $test, Exception $e, $time) {
@@ -177,9 +177,9 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * Skipped test.
  *
- * @param  PHPUnit_Framework_Test $test
- * @param  Exception $e
- * @param  float $time
+ * @param  PHPUnit_Framework_Test $test The test that failed.
+ * @param  Exception $e The skip object.
+ * @param  float $time The current time.
  * @return void
  */
 	public function addSkippedTest(PHPUnit_Framework_Test $test, Exception $e, $time) {
@@ -189,7 +189,7 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * A test suite started.
  *
- * @param  PHPUnit_Framework_TestSuite $suite
+ * @param  PHPUnit_Framework_TestSuite $suite The suite to start
  * @return void
  */
 	public function startTestSuite(PHPUnit_Framework_TestSuite $suite) {
@@ -202,7 +202,7 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * A test suite ended.
  *
- * @param  PHPUnit_Framework_TestSuite $suite
+ * @param  PHPUnit_Framework_TestSuite $suite The suite that ended.
  * @return void
  */
 	public function endTestSuite(PHPUnit_Framework_TestSuite $suite) {
@@ -211,7 +211,7 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * A test started.
  *
- * @param  PHPUnit_Framework_Test $test
+ * @param  PHPUnit_Framework_Test $test The test that started.
  * @return void
  */
 	public function startTest(PHPUnit_Framework_Test $test) {
@@ -220,8 +220,8 @@ class CakeBaseReporter extends PHPUnit_TextUI_ResultPrinter {
 /**
  * A test ended.
  *
- * @param  PHPUnit_Framework_Test $test
- * @param  float $time
+ * @param  PHPUnit_Framework_Test $test The test that ended
+ * @param  float $time The current time.
  * @return void
  */
 	public function endTest(PHPUnit_Framework_Test $test, $time) {

lib/Cake/TestSuite/Reporter/CakeHtmlReporter.php

@@ -169,7 +169,7 @@ class CakeHtmlReporter extends CakeBaseReporter {
 /**
  * Paints a code coverage report.
  *
- * @param array $coverage
+ * @param array $coverage The coverage data
  * @return void
  */
 	public function paintCoverage(array $coverage) {
@@ -243,7 +243,7 @@ class CakeHtmlReporter extends CakeBaseReporter {
  *
  * @param PHPUnit_Framework_AssertionFailedError $message Failure object displayed in
  *   the context of the other tests.
- * @param mixed $test
+ * @param mixed $test The test case to paint a failure for.
  * @return void
  */
 	public function paintFail($message, $test) {
@@ -278,7 +278,7 @@ class CakeHtmlReporter extends CakeBaseReporter {
  * trail of the nesting test suites below the
  * top level test.
  *
- * @param PHPUnit_Framework_Test test method that just passed
+ * @param PHPUnit_Framework_Test $test Test method that just passed
  * @param float $time time spent to run the test method
  * @return void
  */
@@ -295,8 +295,8 @@ class CakeHtmlReporter extends CakeBaseReporter {
 /**
  * Paints a PHP exception.
  *
- * @param Exception $exception Exception to display.
- * @param mixed $test
+ * @param Exception $message Exception to display.
+ * @param mixed $test The test that failed.
  * @return void
  */
 	public function paintException($message, $test) {
@@ -370,7 +370,7 @@ class CakeHtmlReporter extends CakeBaseReporter {
 /**
  * A test suite started.
  *
- * @param PHPUnit_Framework_TestSuite $suite
+ * @param PHPUnit_Framework_TestSuite $suite The test suite to start.
  * @return void
  */
 	public function startTestSuite(PHPUnit_Framework_TestSuite $suite) {