Merge pull request #2959 from bar/3.0-docs

3.0 - Update docs.

src/Database/Connection.php

@@ -25,14 +25,14 @@ use Cake\Database\Log\QueryLogger;
 use Cake\Database\Query;
 
 /**
- * Represents a connection with a database server
+ * Represents a connection with a database server.
  */
 class Connection {
 
 	use TypeConverterTrait;
 
 /**
- * Contains the configuration params for this connection
+ * Contains the configuration params for this connection.
  *
  * @var array
  */
@@ -40,21 +40,21 @@ class Connection {
 
 /**
  * Driver object, responsible for creating the real connection
- * and provide specific SQL dialect
+ * and provide specific SQL dialect.
  *
  * @var \Cake\Database\Driver
  */
 	protected $_driver;
 
 /**
- * Contains how many nested transactions have been started
+ * Contains how many nested transactions have been started.
  *
  * @var int
  */
 	protected $_transactionLevel = 0;
 
 /**
- * Whether a transaction is active in this connection
+ * Whether a transaction is active in this connection.
  *
  * @var int
  */
@@ -62,28 +62,28 @@ class Connection {
 
 /**
  * Whether this connection can and should use savepoints for nested
- * transactions
+ * transactions.
  *
  * @var boolean
  */
 	protected $_useSavePoints = false;
 
 /**
- * Whether to log queries generated during this connection
+ * Whether to log queries generated during this connection.
  *
  * @var boolean
  */
 	protected $_logQueries = false;
 
 /**
- * Logger object instance
+ * Logger object instance.
  *
  * @var QueryLogger
  */
 	protected $_logger = null;
 
 /**
- * Constructor
+ * Constructor.
  *
  * @param array $config configuration for connecting to database
  */
@@ -133,7 +133,7 @@ class Connection {
  * Sets the driver instance. If an string is passed it will be treated
  * as a class name and will be instantiated.
  *
- * If no params are passed it will return the current driver instance
+ * If no params are passed it will return the current driver instance.
  *
  * @param string|Driver $driver
  * @param array|null $config Either config for a new driver or null.
@@ -158,7 +158,7 @@ class Connection {
 	}
 
 /**
- * Connects to the configured database
+ * Connects to the configured database.
  *
  * @throws \Cake\Database\Exception\MissingConnectionException if credentials are invalid
  * @return boolean true on success or false if already connected.
@@ -173,7 +173,7 @@ class Connection {
 	}
 
 /**
- * Disconnects from database server
+ * Disconnects from database server.
  *
  * @return void
  */
@@ -182,7 +182,7 @@ class Connection {
 	}
 
 /**
- * Returns whether connection to database server was already stablished
+ * Returns whether connection to database server was already established.
  *
  * @return boolean
  */
@@ -191,7 +191,7 @@ class Connection {
 	}
 
 /**
- * Prepares a sql statement to be executed
+ * Prepares a SQL statement to be executed.
  *
  * @param string|\Cake\Database\Query $sql
  * @return \Cake\Database\Statement
@@ -208,7 +208,7 @@ class Connection {
 
 /**
  * Executes a query using $params for interpolating values and $types as a hint for each
- * those params
+ * those params.
  *
  * @param string $query SQL to be executed and interpolated with $params
  * @param array $params list or associative array of params to be interpolated in $query as values
@@ -227,7 +227,7 @@ class Connection {
 	}
 
 /**
- * Executes a SQL statement and returns the Statement object as result
+ * Executes a SQL statement and returns the Statement object as result.
  *
  * @param string $sql
  * @return \Cake\Database\Statement
@@ -257,7 +257,7 @@ class Connection {
 	}
 
 /**
- * Executes an INSERT query on the specified table
+ * Executes an INSERT query on the specified table.
  *
  * @param string $table the table to update values in
  * @param array $data values to be inserted
@@ -273,7 +273,7 @@ class Connection {
 	}
 
 /**
- * Executes an UPDATE statement on the specified table
+ * Executes an UPDATE statement on the specified table.
  *
  * @param string $table the table to delete rows from
  * @param array $data values to be updated
@@ -291,7 +291,7 @@ class Connection {
 	}
 
 /**
- * Executes a DELETE  statement on the specified table
+ * Executes a DELETE statement on the specified table.
  *
  * @param string $table the table to delete rows from
  * @param array $conditions conditions to be set for delete statement
@@ -305,7 +305,7 @@ class Connection {
 	}
 
 /**
- * Starts a new transaction
+ * Starts a new transaction.
  *
  * @return void
  */
@@ -327,7 +327,7 @@ class Connection {
 	}
 
 /**
- * Commits current transaction
+ * Commits current transaction.
  *
  * @return boolean true on success, false otherwise
  */
@@ -352,7 +352,7 @@ class Connection {
 	}
 
 /**
- * Rollback current transaction
+ * Rollback current transaction.
  *
  * @return boolean
  */
@@ -384,7 +384,7 @@ class Connection {
  * only if driver the allows it.
  *
  * If you are trying to enable this feature, make sure you check the return value of this
- * function to verify it was enabled successfully
+ * function to verify it was enabled successfully.
  *
  * ## Example:
  *
@@ -408,7 +408,7 @@ class Connection {
 	}
 
 /**
- * Creates a new save point for nested transactions
+ * Creates a new save point for nested transactions.
  *
  * @param string $name
  * @return void
@@ -418,7 +418,7 @@ class Connection {
 	}
 
 /**
- * Releases a save point by its name
+ * Releases a save point by its name.
  *
  * @param string $name
  * @return void
@@ -428,7 +428,7 @@ class Connection {
 	}
 
 /**
- * Rollback a save point by its name
+ * Rollback a save point by its name.
  *
  * @param string $name
  * @return void
@@ -442,9 +442,9 @@ class Connection {
  * while executing the passed callable, the transaction will be rolled back
  * If the result of the callable function is ``false``, the transaction will
  * also be rolled back. Otherwise the transaction is committed after executing
- * the callback
+ * the callback.
  *
- * The callback will receive the connection instance as its first argument..
+ * The callback will receive the connection instance as its first argument.
  *
  * ### Example:
  *
@@ -479,7 +479,7 @@ class Connection {
 	}
 
 /**
- * Quotes value to be used safely in database query
+ * Quotes value to be used safely in database query.
  *
  * @param mixed $value
  * @param string $type Type to be used for determining kind of quoting to perform
@@ -491,7 +491,7 @@ class Connection {
 	}
 
 /**
- * Checks if the driver supports quoting
+ * Checks if the driver supports quoting.
  *
  * @return boolean
  */
@@ -501,7 +501,7 @@ class Connection {
 
 /**
  * Quotes a database identifier (a column name, table name, etc..) to
- * be used safely in queries without the risk of using reserved words
+ * be used safely in queries without the risk of using reserved words.
  *
  * @param string $identifier
  * @return string
@@ -522,7 +522,7 @@ class Connection {
 
 /**
  * Sets the logger object instance. When called with no arguments
- * it returns the currently setup logger instance
+ * it returns the currently setup logger instance.
  *
  * @param object $instance logger object instance
  * @return object logger instance
@@ -538,7 +538,7 @@ class Connection {
 	}
 
 /**
- * Logs a Query string using the configured logger object
+ * Logs a Query string using the configured logger object.
  *
  * @param string $sql string to be logged
  * @return void

src/Database/Query.php

@@ -34,21 +34,21 @@ use IteratorAggregate;
 class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
- * Connection instance to be used to execute this query
+ * Connection instance to be used to execute this query.
  *
  * @var \Cake\Database\Connection
  */
 	protected $_connection;
 
 /**
- * Type of this query (select, insert, update, delete)
+ * Type of this query (select, insert, update, delete).
  *
  * @var string
  */
 	protected $_type;
 
 /**
- * List of SQL parts that will be used to build this query
+ * List of SQL parts that will be used to build this query.
  *
  * @var array
  */
@@ -106,7 +106,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Indicates whether internal state of this query was changed, this is used to
  * discard internal cached objects such as the transformed query or the reference
- * to the executed statement
+ * to the executed statement.
  *
  * @var boolean
  */
@@ -115,14 +115,14 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * A list of callback functions to be called to alter each row from resulting
  * statement upon retrieval. Each one of the callback function will receive
- * the row array as first argument
+ * the row array as first argument.
  *
  * @var array
  */
 	protected $_resultDecorators = [];
 
 /**
- * Statement object resulting from executing this query
+ * Statement object resulting from executing this query.
  *
  * @var Statement
  */
@@ -131,7 +131,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Associative array with the default fields and their types this query might contain
  * used to avoid repetition when calling multiple times functions inside this class that
- * may require a custom type for a specific field
+ * may require a custom type for a specific field.
  *
  * @var array
  */
@@ -146,14 +146,14 @@ class Query implements ExpressionInterface, IteratorAggregate {
 	protected $_valueBinder;
 
 /**
- * Instance of functions builder object used for generating arbitrary SQL functions
+ * Instance of functions builder object used for generating arbitrary SQL functions.
  *
  * @var FunctionsBuilder
  */
 	protected $_functionsBuilder;
 
 /**
- * Constructor
+ * Constructor.
  *
  * @param \Cake\Database\Connection $connection The connection
  * object to be used for transforming and executing this query
@@ -164,7 +164,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Sets the connection instance to be used for executing and transforming this query
- * When called with a null argument, it will return the current connection instance
+ * When called with a null argument, it will return the current connection instance.
  *
  * @param \Cake\Database\Connection $connection instance
  * @return Query|\Cake\Database\Connection
@@ -180,7 +180,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Compiles the SQL representation of this query and executes it using the
- * configured connection object. Returns the resulting statement object
+ * configured connection object. Returns the resulting statement object.
  *
  * Executing a query internally executes several steps, the first one is
  * letting the connection transform this object to fit its particular dialect,
@@ -188,7 +188,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * to actually be executed. Immediately after, literal values are passed to the
  * connection so they are bound to the query in a safe way. Finally, the resulting
  * statement is decorated with custom objects to execute callbacks for each row
- * is retrieved if necessary.
+ * retrieved if necessary.
  *
  * Resulting statement is traversable, so it can be used in any loop as you would
  * with an array.
@@ -219,7 +219,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * values when the query is executed, hence it is most suitable to use with
  * prepared statements.
  *
- * @param ValueBinder $generator A placeholder a value binder object that will hold
+ * @param ValueBinder $generator A placeholder object that will hold
  * associated values for expressions
  * @return string
  */
@@ -237,7 +237,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Returns a callable object that can be used to compile a SQL string representtion
- * of this query
+ * of this query.
  *
  * @param string $sql initial sql string to append to
  * @param \Cake\Database\ValueBinder The placeholder and value binder object
@@ -642,7 +642,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * When creating aliased joins using the array notation, you can override
  * previous join definitions by using the same alias in consequent
  * calls to this function or you can replace all previously defined joins
- * with another list if the third parameter for this function is set to true
+ * with another list if the third parameter for this function is set to true.
  *
  * {{{
  *	$query->join(['alias' => 'table']); // joins table with as alias
@@ -693,7 +693,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * Helper function used to build the string representation of multiple JOIN clauses,
  * it constructs the joins list taking care of aliasing and converting
  * expression objects to string in both the table to be joined and the conditions
- * to be used
+ * to be used.
  *
  * @param array $parts list of joins to be transformed to string
  * @param \Cake\Database\ValueBinder $generator the placeholder generator to be used in expressions
@@ -811,7 +811,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * You can use callable functions to construct complex expressions, functions
  * receive as first argument a new QueryExpression object and this query instance
  * as second argument. Functions must return an expression object, that will be
- * added the list of conditions for the query using th AND operator
+ * added the list of conditions for the query using th AND operator.
  *
  * {{{
  *	$query
@@ -1196,7 +1196,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * required by calling multiple times this method with different queries.
  *
  * By default, the UNION operator will remove duplicate rows, if you wish to include
- * every row for all queries, use unionAll()
+ * every row for all queries, use unionAll().
  *
  * ## Examples
  *
@@ -1302,7 +1302,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Helper function used to covert ExpressionInterface objects inside an array
- * into their string representation
+ * into their string representation.
  *
  * @param array $expressions list of strings and ExpressionInterface objects
  * @param \Cake\Database\ValueBinder $generator the placeholder generator to be used in expressions
@@ -1323,7 +1323,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  * Create an insert query.
  *
  * Note calling this method will reset any data previously set
- * with Query::values()
+ * with Query::values().
  *
  * @param array $columns The columns to insert into.
  * @param array $types A map between columns & their datatypes.
@@ -1541,7 +1541,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
  *
  * The return value for each of those parts may vary. Some clauses use QueryExpression
  * to internally store their state, some use arrays and others may use booleans or
- * integers. This is summary of the return types for each clause
+ * integers. This is summary of the return types for each clause.
  *
  * - update: string The name of the table to update
  * - set: QueryExpression
@@ -1688,6 +1688,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Returns the currently used ValueBinder instance. If a value is passed,
  * it will be set as the new instance to be used.
+ *
  * A ValueBinder is responsible for generating query placeholders and temporarily
  * associate values to those placeholders so that they can be passed correctly
  * statement object.
@@ -1722,7 +1723,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 	}
 
 /**
- * Helper function used to build conditions by composing QueryExpression objects
+ * Helper function used to build conditions by composing QueryExpression objects.
  *
  * @param string name of the query part to append the new part to
  * @param string|array|Expression|callback $append
@@ -1771,7 +1772,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Returns a query object as returned by the connection object as a result of
- * transforming this query instance to conform to any dialect specifics
+ * transforming this query instance to conform to any dialect specifics.
  *
  * @return Query
  */
@@ -1798,7 +1799,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 
 /**
  * Marks a query as dirty, removing any preprocessed information
- * from in memory caching
+ * from in memory caching.
  *
  * @return void
  */
@@ -1812,7 +1813,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 	}
 
 /**
- * Returns string representation of this query (complete SQL statement)
+ * Returns string representation of this query (complete SQL statement).
  *
  * @return string
  */

src/Database/Statement/StatementDecorator.php

@@ -34,14 +34,14 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 
 /**
  * Statement instance implementation, such as PDOStatement
- * or any other custom implementation
+ * or any other custom implementation.
  *
  * @var mixed
  */
 	protected $_statement;
 
 /**
- * Reference to the driver object associated to this statement
+ * Reference to the driver object associated to this statement.
  *
  * @var \Cake\Database\Driver
  */
@@ -59,7 +59,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Magic getter to return $queryString as read-only
+ * Magic getter to return $queryString as read-only.
  *
  * @param string $property internal property to get
  * @return mixed
@@ -75,7 +75,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
  * positional variables you need to start with index one, if using named params then
  * just use the name in any order.
  *
- * It is not allowed to combine positional and named variables in the same statement
+ * It is not allowed to combine positional and named variables in the same statement.
  *
  * ## Examples:
  *
@@ -106,7 +106,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Returns the number of columns this statement's results will contain
+ * Returns the number of columns this statement's results will contain.
  *
  * ## Example:
  *
@@ -123,7 +123,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Returns the error code for the last error that occurred when executing this statement
+ * Returns the error code for the last error that occurred when executing this statement.
  *
  * @return integer|string
  */
@@ -133,7 +133,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 
 /**
  * Returns the error information for the last error that occurred when executing
- * this statement
+ * this statement.
  *
  * @return array
  */
@@ -145,7 +145,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
  * Executes the statement by sending the SQL query to the database. It can optionally
  * take an array or arguments to be bound to the query variables. Please note
  * that binding parameters from this method will not perform any custom type conversion
- * as it would normally happen when calling `bindValue`
+ * as it would normally happen when calling `bindValue`.
  *
  * @param array $params list of values to be bound to query
  * @return boolean true on success, false otherwise
@@ -157,7 +157,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 /**
  * Returns the next row for the result set after executing this statement.
  * Rows can be fetched to contain columns as names or positions. If no
- * rows are left in result set, this method will return false
+ * rows are left in result set, this method will return false.
  *
  * ## Example:
  *
@@ -176,7 +176,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Returns an array with all rows resulting from executing this statement
+ * Returns an array with all rows resulting from executing this statement.
  *
  * ## Example:
  *
@@ -194,7 +194,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Returns the number of rows affected by this SQL statement
+ * Returns the number of rows affected by this SQL statement.
  *
  * ## Example:
  *
@@ -231,8 +231,8 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Statements can be passed as argument for count()
- * to return the number for affected rows from last execution
+ * Statements can be passed as argument for count() to return the number
+ * for affected rows from last execution.
  *
  * @return integer
  */
@@ -241,7 +241,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Binds a set of values to statement object with corresponding type
+ * Binds a set of values to statement object with corresponding type.
  *
  * @param array $params list of values to be bound
  * @param array $types list of types to be used, keys should match those in $params
@@ -267,7 +267,7 @@ class StatementDecorator implements StatementInterface, \Countable, \IteratorAgg
 	}
 
 /**
- * Returns the latest primary inserted using this statement
+ * Returns the latest primary inserted using this statement.
  *
  * @param string $table table name or sequence to get last insert value from
  * @param string column the name of the column representing the primary key

src/Datasource/RepositoryInterface.php

@@ -32,7 +32,7 @@ interface RepositoryInterface {
  * listeners. Any listener can set a valid result set using $query
  *
  * @param string $type the type of query to perform
- * @param array $options An array that will be passed to Query::applyOptions
+ * @param array $options An array that will be passed to Query::applyOptions()
  * @return \Cake\ORM\Query
  */
 	public function find($type = 'all', $options = []);