Fix a pile of API doc errors in Database/

src/Database/Connection.php

@@ -134,11 +134,11 @@ public function configName() {
  *
  * If no params are passed it will return the current driver instance.
  *
- * @param string|Driver $driver
+ * @param string|Driver $driver The driver instance to use.
  * @param array|null $config Either config for a new driver or null.
  * @throws \Cake\Database\Error\MissingDriverException When a driver class is missing.
  * @throws \Cake\Database\Error\MissingExtensionException When a driver's PHP extension is missing.
- * @return Driver
+ * @return \Cake\Database\Driver
  */
 	public function driver($driver = null, $config = null) {
 		if ($driver === null) {
@@ -192,7 +192,7 @@ public function isConnected() {
 /**
  * Prepares a SQL statement to be executed.
  *
- * @param string|\Cake\Database\Query $sql
+ * @param string|\Cake\Database\Query $sql The SQL to convert into a prepared statement.
  * @return \Cake\Database\StatementInterface
  */
 	public function prepare($sql) {
@@ -259,7 +259,7 @@ public function run(Query $query) {
 /**
  * Executes a SQL statement and returns the Statement object as result.
  *
- * @param string $sql
+ * @param string $sql The SQL query to execute.
  * @return \Cake\Database\StatementInterface
  */
 	public function query($sql) {
@@ -271,7 +271,7 @@ public function query($sql) {
 /**
  * Create a new Query instance for this connection.
  *
- * @return Query
+ * @return \Cake\Database\Query
  */
 	public function newQuery() {
 		return new Query($this);
@@ -422,7 +422,7 @@ public function rollback() {
  * `$connection->useSavePoints(false)` Disables usage of savepoints and returns false
  * `$connection->useSavePoints()` Returns current status
  *
- * @param bool|null $enable
+ * @param bool|null $enable Whether or not save points should be used.
  * @return bool true if enabled, false otherwise
  */
 	public function useSavePoints($enable = null) {
@@ -440,7 +440,7 @@ public function useSavePoints($enable = null) {
 /**
  * Creates a new save point for nested transactions.
  *
- * @param string $name
+ * @param string $name The save point name.
  * @return void
  */
 	public function createSavePoint($name) {
@@ -450,7 +450,7 @@ public function createSavePoint($name) {
 /**
  * Releases a save point by its name.
  *
- * @param string $name
+ * @param string $name The save point name.
  * @return void
  */
 	public function releaseSavePoint($name) {
@@ -460,7 +460,7 @@ public function releaseSavePoint($name) {
 /**
  * Rollback a save point by its name.
  *
- * @param string $name
+ * @param string $name The save point name.
  * @return void
  */
 	public function rollbackSavepoint($name) {
@@ -480,7 +480,7 @@ public function rollbackSavepoint($name) {
  *
  * {{{
  * $connection->transactional(function($connection) {
- *	$connection->newQuery()->delete('users')->execute();
+ *   $connection->newQuery()->delete('users')->execute();
  * });
  * }}}
  *
@@ -511,7 +511,7 @@ public function transactional(callable $callback) {
 /**
  * Quotes value to be used safely in database query.
  *
- * @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 mixed quoted value
  */
@@ -533,7 +533,7 @@ public function supportsQuoting() {
  * 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 to quote.
  * @return string
  */
 	public 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
+ * @param null|PDO instance $connection The PDO connection instance.
  * @return mixed connection object used internally
  */
 	public function connection($connection = null) {
@@ -74,7 +74,7 @@ public function disconnect() {
 /**
  * Prepares a sql statement to be executed
  *
- * @param string|\Cake\Database\Query $query
+ * @param string|\Cake\Database\Query $query The query to turn into a prepared statement.
  * @return \Cake\Database\StatementInterface
  */
 	public function prepare($query) {
@@ -124,7 +124,7 @@ public function rollbackTransaction() {
 /**
  * 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
  */

src/Database/Driver/Postgres.php

@@ -94,7 +94,7 @@ public function enabled() {
 /**
  * Sets connection encoding
  *
- * @param string $encoding
+ * @param string $encoding The encoding to use.
  * @return void
  */
 	public function setEncoding($encoding) {
@@ -106,7 +106,7 @@ public function setEncoding($encoding) {
  * Sets connection default schema, if any relation defined in a query is not fully qualified
  * postgres will fallback to looking the relation into defined default schema
  *
- * @param string $schema
+ * @param string $schema The schema names to set `search_path` to.
  * @return void
  */
 	public function setSchema($schema) {

src/Database/Driver/Sqlite.php

@@ -83,7 +83,7 @@ public function enabled() {
 /**
  * Prepares a sql statement to be executed
  *
- * @param string|\Cake\Database\Query $query
+ * @param string|\Cake\Database\Query $query The query to prepare.
  * @return \Cake\Database\StatementInterface
  */
 	public function prepare($query) {

src/Database/Driver/Sqlserver.php

@@ -94,7 +94,7 @@ public function enabled() {
 /**
  * Prepares a sql statement to be executed
  *
- * @param string|\Cake\Database\Query $query
+ * @param string|\Cake\Database\Query $query The query to prepare.
  * @return \Cake\Database\StatementInterface
  */
 	public function prepare($query) {