Commit 56817e5f authored by jhodgdon's avatar jhodgdon

Issue #2057809 by StephaneQ, Berdir, chx, dawehner: Fix up param/return...

Issue #2057809 by StephaneQ, Berdir, chx, dawehner: Fix up param/return documentation in database API
parent 972406d5
......@@ -202,7 +202,7 @@
* @param $options
* An array of options to control how the query operates.
*
* @return DatabaseStatementInterface
* @return \Drupal\Core\Database\StatementInterface
* A prepared statement object, already executed.
*
* @see DatabaseConnection::defaultOptions()
......@@ -234,7 +234,7 @@ function db_query($query, array $args = array(), array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return DatabaseStatementInterface
* @return \Drupal\Core\Database\StatementInterface
* A prepared statement object, already executed.
*
* @see DatabaseConnection::defaultOptions()
......@@ -285,8 +285,8 @@ function db_query_temporary($query, array $args = array(), array $options = arra
* @param $options
* An array of options to control how the query operates.
*
* @return InsertQuery
* A new InsertQuery object for this connection.
* @return \Drupal\Core\Database\Query\Insert
* A new Insert object for this connection.
*/
function db_insert($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
......@@ -303,8 +303,8 @@ function db_insert($table, array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return MergeQuery
* A new MergeQuery object for this connection.
* @return \Drupal\Core\Database\Query\Merge
* A new Merge object for this connection.
*/
function db_merge($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
......@@ -321,8 +321,8 @@ function db_merge($table, array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return UpdateQuery
* A new UpdateQuery object for this connection.
* @return \Drupal\Core\Database\Query\Update
* A new Update object for this connection.
*/
function db_update($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
......@@ -339,8 +339,8 @@ function db_update($table, array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return DeleteQuery
* A new DeleteQuery object for this connection.
* @return \Drupal\Core\Database\Query\Delete
* A new Delete object for this connection.
*/
function db_delete($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
......@@ -357,8 +357,8 @@ function db_delete($table, array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return TruncateQuery
* A new TruncateQuery object for this connection.
* @return \Drupal\Core\Database\Query\Truncate
* A new Truncate object for this connection.
*/
function db_truncate($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
......@@ -378,8 +378,8 @@ function db_truncate($table, array $options = array()) {
* @param $options
* An array of options to control how the query operates.
*
* @return SelectQuery
* A new SelectQuery object for this connection.
* @return \Drupal\Core\Database\Query\Select
* A new Select object for this connection.
*/
function db_select($table, $alias = NULL, array $options = array()) {
if (empty($options['target'])) {
......@@ -397,8 +397,8 @@ function db_select($table, $alias = NULL, array $options = array()) {
* An array of options to control how the transaction operates:
* - target: The database target name.
*
* @return DatabaseTransaction
* A new DatabaseTransaction object for this connection.
* @return \Drupal\Core\Database\Transaction
* A new Transaction object for this connection.
*/
function db_transaction($name = NULL, array $options = array()) {
if (empty($options['target'])) {
......@@ -530,7 +530,8 @@ function db_next_id($existing_id = 0) {
/**
* Returns a new DatabaseCondition, set to "OR" all conditions together.
*
* @return Condition
* @return \Drupal\Core\Database\Query\Condition
* A new Condition object, set to "OR" all conditions together.
*/
function db_or() {
return new Condition('OR');
......@@ -539,7 +540,8 @@ function db_or() {
/**
* Returns a new DatabaseCondition, set to "AND" all conditions together.
*
* @return Condition
* @return \Drupal\Core\Database\Query\Condition
* A new Condition object, set to "AND" all conditions together.
*/
function db_and() {
return new Condition('AND');
......@@ -548,7 +550,8 @@ function db_and() {
/**
* Returns a new DatabaseCondition, set to "XOR" all conditions together.
*
* @return Condition
* @return \Drupal\Core\Database\Query\Condition
* A new Condition object, set to "XOR" all conditions together.
*/
function db_xor() {
return new Condition('XOR');
......@@ -562,7 +565,9 @@ function db_xor() {
*
* @param $conjunction
* The conjunction to use for query conditions (AND, OR or XOR).
* @return Condition
*
* @return \Drupal\Core\Database\Query\Condition
* A new Condition object, set to the specified conjunction.
*/
function db_condition($conjunction) {
return new Condition($conjunction);
......
......@@ -330,7 +330,7 @@ public function tablePrefix($table = 'default') {
* The query string as SQL, with curly-braces surrounding the
* table names.
*
* @return Drupal\Core\Database\StatementInterface
* @return \Drupal\Core\Database\StatementInterface
* A PDO prepared statement ready for its execute() method.
*/
public function prepareQuery($query) {
......@@ -402,7 +402,7 @@ public function setLogger(Log $logger) {
/**
* Gets the current logging object for this connection.
*
* @return DatabaseLog
* @return \Drupal\Core\Database\Log
* The current logging object for this connection. If there isn't one,
* NULL is returned.
*/
......@@ -679,7 +679,7 @@ public function select($table, $alias = NULL, array $options = array()) {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\Query\Insert
* @return \Drupal\Core\Database\Query\Insert
* A new Insert query object.
*
* @see Drupal\Core\Database\Query\Insert
......@@ -695,7 +695,7 @@ public function insert($table, array $options = array()) {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* A new Merge query object.
*
* @see Drupal\Core\Database\Query\Merge
......@@ -712,7 +712,7 @@ public function merge($table, array $options = array()) {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\Query\Update
* @return \Drupal\Core\Database\Query\Update
* A new Update query object.
*
* @see Drupal\Core\Database\Query\Update
......@@ -728,7 +728,7 @@ public function update($table, array $options = array()) {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\Query\Delete
* @return \Drupal\Core\Database\Query\Delete
* A new Delete query object.
*
* @see Drupal\Core\Database\Query\Delete
......@@ -744,7 +744,7 @@ public function delete($table, array $options = array()) {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\Query\Truncate
* @return \Drupal\Core\Database\Query\Truncate
* A new Truncate query object.
*
* @see Drupal\Core\Database\Query\Truncate
......@@ -759,7 +759,7 @@ public function truncate($table, array $options = array()) {
*
* This method will lazy-load the appropriate schema library file.
*
* @return Drupal\Core\Database\Schema
* @return \Drupal\Core\Database\Schema
* The database Schema object for this connection.
*/
public function schema() {
......@@ -879,8 +879,8 @@ public function transactionDepth() {
* @param $name
* Optional name of the savepoint.
*
* @return Drupal\Core\Database\Transaction
* A DatabaseTransaction object.
* @return \Drupal\Core\Database\Transaction
* A Transaction object.
*
* @see Drupal\Core\Database\Transaction
*/
......@@ -1046,7 +1046,7 @@ protected function popCommittableTransactions() {
* @param $options
* An array of options on the query.
*
* @return Drupal\Core\Database\StatementInterface
* @return \Drupal\Core\Database\StatementInterface
* A database query result resource, or NULL if the query was not executed
* correctly.
*/
......
......@@ -90,7 +90,7 @@ abstract class Database {
* @param $key
* The database connection key for which we want to log.
*
* @return Drupal\Core\Database\Log
* @return \Drupal\Core\Database\Log
* The query log object. Note that the log object does support richer
* methods than the few exposed through the Database class, so in some
* cases it may be desirable to access it directly.
......@@ -149,7 +149,7 @@ abstract class Database {
* @param $key
* The database connection key. Defaults to NULL which means the active key.
*
* @return Drupal\Core\Database\Connection
* @return \Drupal\Core\Database\Connection
* The corresponding connection object.
*/
final public static function getConnection($target = 'default', $key = NULL) {
......
......@@ -24,7 +24,7 @@ interface AlterableInterface {
* @param $tag
* The tag to add.
*
* @return Drupal\Core\Database\Query\AlterableInterface
* @return \Drupal\Core\Database\Query\AlterableInterface
* The called object.
*/
public function addTag($tag);
......@@ -77,7 +77,7 @@ public function hasAnyTag();
* @param $object
* The additional data to add to the query. May be any valid PHP variable.
*
* @return Drupal\Core\Database\Query\AlterableInterface
* @return \Drupal\Core\Database\Query\AlterableInterface
* The called object.
*/
public function addMetaData($key, $object);
......
......@@ -36,7 +36,7 @@ interface ConditionInterface {
* complex options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is
* an array, and = otherwise.
*
* @return QueryConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*
* @see Drupal\Core\Database\Query\ConditionInterface::isNull()
......@@ -53,7 +53,7 @@ public function condition($field, $value = NULL, $operator = NULL);
* @param $args
* An associative array of arguments.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function where($snippet, $args = array());
......@@ -64,7 +64,7 @@ public function where($snippet, $args = array());
* @param $field
* The name of the field to check.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function isNull($field);
......@@ -75,7 +75,7 @@ public function isNull($field);
* @param $field
* The name of the field to check.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function isNotNull($field);
......@@ -83,10 +83,10 @@ public function isNotNull($field);
/**
* Sets a condition that the specified subquery returns values.
*
* @param Drupal\Core\Database\Query\SelectInterface $select
* @param \Drupal\Core\Database\Query\SelectInterface $select
* The subquery that must contain results.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function exists(SelectInterface $select);
......@@ -94,10 +94,10 @@ public function exists(SelectInterface $select);
/**
* Sets a condition that the specified subquery returns no values.
*
* @param Drupal\Core\Database\Query\SelectInterface $select
* @param \Drupal\Core\Database\Query\SelectInterface $select
* The subquery that must not contain results.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function notExists(SelectInterface $select);
......
......@@ -34,8 +34,8 @@ class Delete extends Query implements ConditionInterface {
/**
* Constructs a Delete object.
*
* @param Drupal\Core\Database\Connection $connection
* A DatabaseConnection object.
* @param \Drupal\Core\Database\Connection $connection
* A Connection object.
* @param string $table
* Name of the table to associate with this query.
* @param array $options
......
......@@ -26,7 +26,7 @@ interface ExtendableInterface {
* The base name of the extending class. The base name will be checked
* against the current database connection to allow driver-specific subclasses
* as well, using the same logic as the query objects themselves.
* @return Drupal\Core\Database\Query\ExtendableInterface
* @return \Drupal\Core\Database\Query\ExtendableInterface
* The extender object, which now contains a reference to this object.
*/
public function extend($extender_name);
......
......@@ -62,8 +62,8 @@ class Insert extends Query {
/**
* Constructs an Insert object.
*
* @param Drupal\Core\Database\Connection $connection
* A DatabaseConnection object.
* @param \Drupal\Core\Database\Connection $connection
* A Connection object.
* @param string $table
* Name of the table to associate with this query.
* @param array $options
......@@ -94,7 +94,7 @@ public function __construct($connection, $table, array $options = array()) {
* An array of fields to insert into the database. The values must be
* specified in the same order as the $fields array.
*
* @return Drupal\Core\Database\Query\Insert
* @return \Drupal\Core\Database\Query\Insert
* The called object.
*/
public function fields(array $fields, array $values = array()) {
......@@ -125,7 +125,7 @@ public function fields(array $fields, array $values = array()) {
* @param $values
* An array of values to add to the query.
*
* @return Drupal\Core\Database\Query\Insert
* @return \Drupal\Core\Database\Query\Insert
* The called object.
*/
public function values(array $values) {
......@@ -159,7 +159,7 @@ public function values(array $values) {
* An array of values for which to use the default values
* specified in the table definition.
*
* @return Drupal\Core\Database\Query\Insert
* @return \Drupal\Core\Database\Query\Insert
* The called object.
*/
public function useDefaults(array $fields) {
......@@ -170,10 +170,10 @@ public function useDefaults(array $fields) {
/**
* Sets the fromQuery on this InsertQuery object.
*
* @param SelectQueryInterface $query
* @param \Drupal\Core\Database\Query\SelectInterface $query
* The query to fetch the rows that should be inserted.
*
* @return InsertQuery
* @return \Drupal\Core\Database\Query\Insert
* The called object.
*/
public function from(SelectInterface $query) {
......
......@@ -126,8 +126,8 @@ class Merge extends Query implements ConditionInterface {
/**
* Constructs a Merge object.
*
* @param Drupal\Core\Database\Connection $connection
* A Drupal\Core\Database\Connection object.
* @param \Drupal\Core\Database\Connection $connection
* A Connection object.
* @param string $table
* Name of the table to associate with this query.
* @param array $options
......@@ -148,7 +148,7 @@ public function __construct(Connection $connection, $table, array $options = arr
* The table name or the subquery to be used. Use a Select query object to
* pass in a subquery.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
protected function conditionTable($table) {
......@@ -163,7 +163,7 @@ protected function conditionTable($table) {
* An associative array of fields to write into the database. The array keys
* are the field names and the values are the values to which to set them.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function updateFields(array $fields) {
......@@ -188,7 +188,7 @@ public function updateFields(array $fields) {
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function expression($field, $expression, array $arguments = NULL) {
......@@ -213,7 +213,7 @@ public function expression($field, $expression, array $arguments = NULL) {
* An array of fields to insert into the database. The values must be
* specified in the same order as the $fields array.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function insertFields(array $fields, array $values = array()) {
......@@ -240,7 +240,7 @@ public function insertFields(array $fields, array $values = array()) {
* An array of values for which to use the default values
* specified in the table definition.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function useDefaults(array $fields) {
......@@ -266,7 +266,7 @@ public function useDefaults(array $fields) {
* An array of values to set into the database. The values must be
* specified in the same order as the $fields array.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function fields(array $fields, array $values = array()) {
......@@ -300,7 +300,7 @@ public function fields(array $fields, array $values = array()) {
* An array of values to set into the database. The values must be
* specified in the same order as the $fields array.
*
* @return Drupal\Core\Database\Query\Merge
* @return \Drupal\Core\Database\Query\Merge
* The called object.
*/
public function key(array $fields, array $values = array()) {
......
......@@ -104,7 +104,7 @@ protected function ensureElement() {
* You will rarely need to specify a count query directly. If not specified,
* one is generated off of the pager query itself.
*
* @param SelectQueryInterface $query
* @param \Drupal\Core\Database\Query\SelectInterface $query
* The count query object. It must return a single row with a single column,
* which is the total number of records.
*/
......@@ -118,7 +118,7 @@ public function setCountQuery(SelectInterface $query) {
* The count query may be specified manually or, by default, taken from the
* query we are extending.
*
* @return SelectQueryInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* A count query object.
*/
public function getCountQuery() {
......
......@@ -66,7 +66,7 @@ abstract class Query implements PlaceholderInterface {
/**
* Constructs a Query object.
*
* @param Drupal\Core\Database\Connection $connection
* @param \Drupal\Core\Database\Connection $connection
* Database connection object.
* @param array $options
* Array of query options.
......@@ -151,7 +151,7 @@ public function nextPlaceholder() {
* @param $comment
* The comment string to be inserted into the query.
*
* @return Drupal\Core\Database\Query\Query
* @return \Drupal\Core\Database\Query\Query
* The called object.
*/
public function comment($comment) {
......
......@@ -598,7 +598,7 @@ public function countQuery() {
/**
* Prepares a count query from the current query object.
*
* @return Drupal\Core\Database\Query\Select
* @return \Drupal\Core\Database\Query\Select
* A new query object ready to have COUNT(*) performed on it.
*/
protected function prepareCountQuery() {
......
......@@ -142,7 +142,7 @@ public function getArguments(PlaceholderInterface $queryPlaceholder = NULL);
*
* @param $distinct
* TRUE to flag this query DISTINCT, FALSE to disable it.
* @return SelectQueryInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function distinct($distinct = TRUE);
......@@ -184,7 +184,7 @@ public function addField($table_alias, $field, $alias = NULL);
* An indexed array of fields present in the specified table that should be
* included in this query. If not specified, $table_alias.* will be generated
* without any aliases.
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function fields($table_alias, array $fields = array());
......@@ -352,7 +352,7 @@ public function addJoin($type, $table, $alias = NULL, $condition = NULL, $argume
* The field on which to order.
* @param $direction
* The direction to sort. Legal values are "ASC" and "DESC".
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function orderBy($field, $direction = 'ASC');
......@@ -374,7 +374,7 @@ public function orderBy($field, $direction = 'ASC');
*
* for an example of such an alternate sorting mechanism.
*
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object
*/
public function orderRandom();
......@@ -390,7 +390,7 @@ public function orderRandom();
* range directives that are set.
* @param $length
* The number of records to return from the result set.
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function range($start = NULL, $length = NULL);
......@@ -415,7 +415,7 @@ public function range($start = NULL, $length = NULL);
* @param $type
* The type of UNION to add to the query. Defaults to plain
* UNION.
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function union(SelectInterface $query, $type = '');
......@@ -425,7 +425,7 @@ public function union(SelectInterface $query, $type = '');
*
* @param $field
* The field on which to group. This should be the field as aliased.
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*/
public function groupBy($field);
......@@ -433,7 +433,7 @@ public function groupBy($field);
/**
* Get the equivalent COUNT query of this query as a new query object.
*
* @return Drupal\Core\Database\Query\SelectInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* A new SelectQuery object with no fields or expressions besides COUNT(*).
*/
public function countQuery();
......@@ -472,7 +472,7 @@ public function preExecute(SelectInterface $query = NULL);
* The comparison operator, such as =, <, or >=. It also accepts more complex
* options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is an array
* = otherwise.
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function havingCondition($field, $value = NULL, $operator = NULL);
......@@ -497,7 +497,7 @@ public function __clone();
* @param $set
* IF TRUE, FOR UPDATE will be added to the query, if FALSE then it won't.
*
* @return Drupal\Core\Database\Query\ConditionInterface
* @return \Drupal\Core\Database\Query\ConditionInterface
* The called object.
*/
public function forUpdate($set = TRUE);
......
......@@ -34,7 +34,7 @@ public function __construct(SelectInterface $query, Connection $connection) {
* @param array $header
* Table header array.
*
* @return SelectQueryInterface
* @return \Drupal\Core\Database\Query\SelectInterface
* The called object.
*
* @see theme_table()
......
......@@ -26,8 +26,8 @@ class Truncate extends Query {
/**
* Constructs a Truncate query object.
*
* @param DatabaseConnection $connection
* A DatabaseConnection object.
* @param \Drupal\Core\Database\Connection $connection
* A Connection object.
* @param string $table
* Name of the table to associate with this query.
* @param array $options
......
......@@ -63,7 +63,7 @@ class Update extends Query implements ConditionInterface {
/**
* Constructs an Update query object.
*
* @param Drupal\Core\Database\Connection $connection
* @param \Drupal\Core\Database\Connection $connection
* A Connection object.
* @param string $table
* Name of the table to associate with this query.
......@@ -161,7 +161,7 @@ public function compiled() {
* An associative array of fields to write into the database. The array keys
* are the field names and the values are the values to which to set them.
*
* @return Drupal\Core\Database\Query\Update
* @return \Drupal\Core\Database\Query\Update
* The called object.
*/
public function fields(array $fields) {
......@@ -184,7 +184,7 @@ public function fields(array $fields) {
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
*