Commit 1b01b241 authored by Dries's avatar Dries

- Patch #648744 by Crell: specified more @return type definitions for auto-completion in IDEs.

parent 99128df8
......@@ -27,7 +27,7 @@ public function __construct($file_path);
* @param $file_path
* The full system path of the file or directory to add. Only local files
* and directories are supported.
* @return
* @return ArchiverInterface
* The called object.
*/
public function add($file_path);
......@@ -37,7 +37,7 @@ public function add($file_path);
*
* @param $path
* The file name relative to the root of the archive to remove.
* @return
* @return ArchiverInterface
* The called object.
*/
public function remove($path);
......@@ -51,7 +51,7 @@ public function remove($path);
* Optionally specify a list of files to be extracted. Files are
* relative to the root of the archive. If not specified, all files
* in the archive will be extracted
* @return
* @return ArchiverInterface
* The called object.
*/
public function extract($path, Array $files = array());
......
......@@ -12,6 +12,8 @@
*
* @param $bin
* The cache bin for which the cache object should be returned.
* @return DrupalCacheInterface
* The cache object associated with the specified bin.
*/
function _cache_get_object($bin) {
// We do not use drupal_static() here because we do not want to change the
......
......@@ -446,7 +446,7 @@ public function prefixTables($sql) {
* Whether or not to cache the prepared statement for later reuse in this
* same request. Usually we want to, but queries that require preprocessing
* cannot be safely cached.
* @return
* @return DatabaseStatementInterface
* A PDO prepared statement ready for its execute() method.
*/
public function prepareQuery($query, $cache = TRUE) {
......@@ -499,7 +499,7 @@ public function setLogger(DatabaseLog $logger) {
/**
* Get the current logging object for this connection.
*
* @return
* @return DatabaseLog
* The current logging object for this connection. If there isn't one,
* NULL is returned.
*/
......@@ -548,7 +548,7 @@ public function makeSequenceName($table, $field) {
* @param $options
* An associative array of options to control how the query is run. See
* the documentation for DatabaseConnection::defaultOptions() for details.
* @return
* @return DatabaseStatementInterface
* This method will return one of: The executed statement, the number of
* rows affected by the query (not the number matched), or the generated
* insert id of the last query, depending on the value of $options['return'].
......@@ -670,7 +670,7 @@ protected function expandArguments(&$query, &$args) {
* The alias of the base table of this query.
* @param $options
* An array of options on the query.
* @return
* @return SelectQueryInterface
* A new SelectQuery object.
*/
public function select($table, $alias = NULL, array $options = array()) {
......@@ -694,7 +694,7 @@ public function select($table, $alias = NULL, array $options = array()) {
* @see InsertQuery
* @param $options
* An array of options on the query.
* @return
* @return InsertQuery
* A new InsertQuery object.
*/
public function insert($table, array $options = array()) {
......@@ -714,7 +714,7 @@ public function insert($table, array $options = array()) {
* @see MergeQuery
* @param $options
* An array of options on the query.
* @return
* @return MergeQuery
* A new MergeQuery object.
*/
public function merge($table, array $options = array()) {
......@@ -735,7 +735,7 @@ public function merge($table, array $options = array()) {
* @see UpdateQuery
* @param $options
* An array of options on the query.
* @return
* @return UpdateQuery
* A new UpdateQuery object.
*/
public function update($table, array $options = array()) {
......@@ -755,7 +755,7 @@ public function update($table, array $options = array()) {
* @see DeleteQuery
* @param $options
* An array of options on the query.
* @return
* @return DeleteQuery
* A new DeleteQuery object.
*/
public function delete($table, array $options = array()) {
......@@ -775,7 +775,7 @@ public function delete($table, array $options = array()) {
* @see TruncateQuery
* @param $options
* An array of options on the query.
* @return
* @return TruncateQuery
* A new DeleteQuery object.
*/
public function truncate($table, array $options = array()) {
......@@ -794,7 +794,7 @@ public function truncate($table, array $options = array()) {
*
* This method will lazy-load the appropriate schema library file.
*
* @return
* @return DatabaseSchema
* The DatabaseSchema object for this connection.
*/
public function schema() {
......@@ -888,7 +888,7 @@ public function rollback($type = NULL, $message = NULL, $variables = array(), $s
$severity = $logging['default_severity'];
}
}
// Record in an array to send to the log after transaction rollback. Messages written
// directly to a log (with a database back-end) will roll back during the following
// transaction rollback. This is an array because rollback could be requested multiple
......@@ -973,11 +973,11 @@ public function popTransaction() {
// Log the failed rollback.
$logging_callback('database', 'Explicit rollback failed: not supported on active connection.', array(), $logging['error_severity']);
}
// It would be nice to throw an exception here if logging failed,
// but throwing exceptions in destructors is not supported.
}
if (isset($logging_callback)) {
// Play back the logged errors to the specified logging callback post-rollback.
foreach ($this->rollbackLogs as $log_item) {
......@@ -987,7 +987,7 @@ public function popTransaction() {
// Reset any scheduled rollback.
$this->willRollback = FALSE;
// Reset the error logs.
$this->rollbackLogs = array();
}
......@@ -1015,7 +1015,7 @@ public function popTransaction() {
* The maximum number of result rows to return.
* @param $options
* An array of options on the query.
* @return
* @return DatabaseStatementInterface
* A database query result resource, or NULL if the query was not executed
* correctly.
*/
......@@ -1257,7 +1257,7 @@ abstract class Database {
* The logging key to log.
* @param $key
* The database connection key for which we want to log.
* @return
* @return DatabaseLog
* 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.
......@@ -1297,7 +1297,7 @@ abstract class Database {
'error_severity' => $error_severity,
);
}
/**
* Get the logging callback for notices and errors.
*
......@@ -1309,7 +1309,7 @@ abstract class Database {
final public static function getLoggingCallback() {
return self::$logging_callback;
}
/**
* Retrieve the queries logged on for given logging key.
*
......@@ -1323,7 +1323,7 @@ abstract class Database {
* The logging key to log.
* @param $key
* The database connection key for which we want to log.
* @return
* @return array
* The query log for the specified logging key and connection.
*/
final public static function getLog($logging_key, $key = 'default') {
......@@ -1343,7 +1343,7 @@ abstract class Database {
* @param $key
* The database connection key. Defaults to NULL which means the active
* key.
* @return
* @return DatabaseConnection
* The corresponding connection object.
*/
final public static function getConnection($target = 'default', $key = NULL) {
......
......@@ -221,7 +221,7 @@ protected function throwPDOException() {
* The query.
* @param array $args
* An array of arguments.
* @return
* @return PDOStatement
* A PDOStatement object.
*/
protected function getStatement($query, &$args = array()) {
......
......@@ -33,7 +33,7 @@ interface QueryConditionInterface {
* 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
* @return QueryConditionInterface
* The called object.
*/
public function condition($field, $value = NULL, $operator = NULL);
......@@ -46,7 +46,7 @@ public function condition($field, $value = NULL, $operator = NULL);
* not ? placeholders.
* @param $args
* An associative array of arguments.
* @return
* @return QueryConditionInterface
* The called object.
*/
public function where($snippet, $args = array());
......@@ -56,7 +56,7 @@ public function where($snippet, $args = array());
*
* @param $field
* The name of the field to check.
* @return
* @return QueryConditionInterface
* The called object.
*/
public function isNull($field);
......@@ -66,7 +66,7 @@ public function isNull($field);
*
* @param $field
* The name of the field to check.
* @return
* @return QueryConditionInterface
* The called object.
*/
public function isNotNull($field);
......@@ -135,7 +135,7 @@ interface QueryAlterableInterface {
*
* @param $tag
* The tag to add.
* @return
* @return QueryAlterableInterface
* The called object.
*/
public function addTag($tag);
......@@ -183,7 +183,7 @@ public function hasAnyTag();
* follows the same rules as any other PHP identifier.
* @param $object
* The additional data to add to the query. May be any valid PHP variable.
* @return
* @return QueryAlterableInterface
* The called object.
*/
public function addMetaData($key, $object);
......@@ -203,8 +203,12 @@ public function getMetaData($key);
* Interface for a query that accepts placeholders.
*/
interface QueryPlaceholderInterface {
/**
* Returns the next placeholder for the query.
* Returns the next placeholder ID for the query.
*
* @return
* The next available placeholder ID as an integer.
*/
function nextPlaceholder();
}
......@@ -339,7 +343,7 @@ public function __construct($connection, $table, array $options = array()) {
* @param $values
* An array of fields to insert into the database. The values must be
* specified in the same order as the $fields array.
* @return
* @return InsertQuery
* The called object.
*/
public function fields(array $fields, array $values = array()) {
......@@ -369,7 +373,7 @@ public function fields(array $fields, array $values = array()) {
*
* @param $values
* An array of values to add to the query.
* @return
* @return InsertQuery
* The called object.
*/
public function values(array $values) {
......@@ -402,7 +406,7 @@ public function values(array $values) {
* @param $fields
* An array of values for which to use the default values
* specified in the table definition.
* @return
* @return InsertQuery
* The called object.
*/
public function useDefaults(array $fields) {
......@@ -429,7 +433,7 @@ public function useDefaults(array $fields) {
*
* @param $delay
* If TRUE, this query is delay-safe and will run delayed on supported databases.
* @return
* @return InsertQuery
* The called object.
*/
public function delay($delay = TRUE) {
......@@ -628,7 +632,7 @@ public function __construct($connection, $table, array $options = array()) {
* @param $values
* An array of fields to set into the database. The values must be
* specified in the same order as the $fields array.
* @return
* @return MergeQuery
* The called object.
*/
public function fields(array $fields, array $values = array()) {
......@@ -662,7 +666,7 @@ public function fields(array $fields, array $values = array()) {
* @param $values
* An array of fields to set into the database. The values must be
* specified in the same order as the $fields array.
* @return
* @return MergeQuery
* The called object.
*/
public function key(array $fields, array $values = array()) {
......@@ -686,7 +690,7 @@ public function key(array $fields, array $values = array()) {
* @param $values
* An array of fields to set into the database. The values must be
* specified in the same order as the $fields array.
* @return
* @return MergeQuery
* The called object.
*/
public function update(array $fields, array $values = array()) {
......@@ -715,7 +719,7 @@ public function update(array $fields, array $values = array()) {
* specified by the fields() method.
* Alternatively, the fields may be specified as a variable number of string
* parameters.
* @return
* @return MergeQuery
* The called object.
*/
public function updateExcept($exclude_fields) {
......@@ -742,7 +746,7 @@ public function updateExcept($exclude_fields) {
* @param $arguments
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
* @return
* @return MergeQuery
* The called object.
*/
public function expression($field, $expression, array $arguments = NULL) {
......@@ -1059,7 +1063,7 @@ public function compile(DatabaseConnection $connection, QueryPlaceholderInterfac
* @param $fields
* An associative array of fields to write into the database. The array keys
* are the field names while the values are the values to which to set them.
* @return
* @return UpdateQuery
* The called object.
*/
public function fields(array $fields) {
......@@ -1081,7 +1085,7 @@ public function fields(array $fields) {
* @param $arguments
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
* @return
* @return UpdateQuery
* The called object.
*/
public function expression($field, $expression, array $arguments = NULL) {
......@@ -1353,7 +1357,7 @@ protected function mapConditionOperator($operator) {
/**
* Returns a new DatabaseCondition, set to "OR" all conditions together.
*
*
* @return DatabaseCondition
*/
function db_or() {
......@@ -1362,7 +1366,7 @@ function db_or() {
/**
* Returns a new DatabaseCondition, set to "AND" all conditions together.
*
*
* @return DatabaseCondition
*/
function db_and() {
......@@ -1371,7 +1375,7 @@ function db_and() {
/**
* Returns a new DatabaseCondition, set to "XOR" all conditions together.
*
*
* @return DatabaseCondition
*/
function db_xor() {
......
......@@ -183,7 +183,7 @@ public function nextPlaceholder() {
* The name of the table to explode.
* @param $operator
* The operator to apply on the 'table' part of the condition.
* @return
* @return QueryConditionInterface
* A DatabaseCondition object.
*/
protected function buildTableNameCondition($table_name, $operator = '=') {
......
......@@ -26,7 +26,7 @@ interface QueryExtendableInterface {
* against the current database connection to allow driver-specific subclasses
* as well, using the same logic as the query objects themselves. For example,
* PagerDefault_mysql is the MySQL-specific override for PagerDefault.
* @return
* @return QueryExtendableInterface
* The extender object, which now contains a reference to this object.
*/
public function extend($extender_name);
......@@ -149,7 +149,7 @@ public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL)
*
* @param $distinct
* TRUE to flag this query DISTINCT, FALSE to disable it.
* @return
* @return SelectQueryInterface
* The called object.
*/
public function distinct($distinct = TRUE);
......@@ -191,7 +191,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
* @return SelectQueryInterface
* The called object.
*/
public function fields($table_alias, array $fields = array());
......@@ -342,7 +342,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
* @return SelectQueryInterface
* The called object.
*/
public function orderBy($field, $direction = 'ASC');
......@@ -364,7 +364,7 @@ public function orderBy($field, $direction = 'ASC');
*
* for an example of such an alternate sorting mechanism.
*
* @return
* @return SelectQueryInterface
* The called object
*/
public function orderRandom();
......@@ -380,7 +380,7 @@ public function orderRandom();
* range directives that are set.
* @param $limit
* The number of records to return from the result set.
* @return
* @return SelectQueryInterface
* The called object.
*/
public function range($start = NULL, $length = NULL);
......@@ -405,7 +405,7 @@ public function range($start = NULL, $length = NULL);
* @param $type
* The type of UNION to add to the query. Defaults to plain
* UNION.
* @return
* @return SelectQueryInterface
* The called object.
*/
public function union(SelectQueryInterface $query, $type = '');
......@@ -415,7 +415,7 @@ public function union(SelectQueryInterface $query, $type = '');
*
* @param $field
* The field on which to group. This should be the field as aliased.
* @return
* @return SelectQueryInterface
* The called object.
*/
public function groupBy($field);
......@@ -423,13 +423,16 @@ public function groupBy($field);
/**
* Get the equivalent COUNT query of this query as a new query object.
*
* @return
* @return SelectQueryInterface
* A new SelectQuery object with no fields or expressions besides COUNT(*).
*/
public function countQuery();
/**
* Indicates if preExecute() has already been called on that object.
*
* @return
* TRUE is this query has already been prepared, FALSE otherwise.
*/
public function isPrepared();
......
......@@ -27,10 +27,11 @@ function __construct($jail) {
abstract static function factory($jail, $settings);
/**
* Implementation of the magic __get() method. If the connection isn't set to
* anything, this will call the connect() method and set it to and return the
* result; afterwards, the connection will be returned directly without using
* this method.
* Implementation of the magic __get() method.
*
* If the connection isn't set to anything, this will call the connect() method
* and set it to and return the result; afterwards, the connection will be
* returned directly without using this method.
*/
function __get($name) {
if ($name == 'connection') {
......@@ -80,7 +81,7 @@ function __get($name) {
$this->checkPath($path);
$this->chmodJailed($path, $mode, $recursive);
}
/**
* Creates a directory.
*
......@@ -156,7 +157,7 @@ function __get($name) {
* @param $path
* @param $strip_chroot
*
* @return string;
* @return string
*/
protected final function fixRemotePath($path, $strip_chroot = TRUE) {
$path = $this->sanitizePath($path);
......@@ -173,7 +174,7 @@ function __get($name) {
* Changes backslahes to slashes, also removes a trailing slash.
*
* @param string $path
* @return string;
* @return string
*/
function sanitizePath($path) {
$path = str_replace('\\', '/', $path); // Windows path sanitiation.
......
......@@ -5,7 +5,7 @@
* Base class for FTP implementations.
*/
abstract class FileTransferFTP extends FileTransfer {
public function __construct($jail, $username, $password, $hostname, $port) {
$this->username = $username;
$this->password = $password;
......@@ -19,7 +19,7 @@ public function __construct($jail, $username, $password, $hostname, $port) {
*
* @param string $jail
* @param array $settings
* @return
* @return FileTransferFTP
* The appropriate FileTransferFTP subclass based on the available
* options. If the FTP PHP extension is available, use it. Otherwise, we
* try to use the FTP file stream support.
......@@ -27,7 +27,7 @@ public function __construct($jail, $username, $password, $hostname, $port) {
static function factory($jail, $settings) {
$settings['hostname'] = empty($settings['hostname']) ? 'localhost' : $settings['hostname'];
$settings['port'] = empty($settings['port']) ? 21 : $settings['port'];
if (function_exists('ftp_connect')) {
$class = 'FileTransferFTPExtension';
}
......@@ -46,7 +46,7 @@ static function factory($jail, $settings) {
* Connection class using the FTP URL wrapper.
*/
class FileTransferFTPWrapper extends FileTransferFTP {
function connect() {
$this->connection = 'ftp://' . urlencode($this->username) . ':' . urlencode($this->password) . '@' . $this->hostname . ':' . $this->port . '/';
if (!is_dir($this->connection)) {
......
......@@ -183,7 +183,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
* default. To specificy a different class for all mail sent by one module, set
* the class name as the value for the key corresponding to the module name. To
* specificy a class for a particular message sent by one module, set the class
* name as the value for the array key that is the message id, which is
* name as the value for the array key that is the message id, which is
* "${module}_${key}".
*
* For example to debug all mail sent by the user module by logging it to a
......@@ -218,6 +218,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
* @param $key
* A key to identify the e-mail sent. The final e-mail ID for the e-mail
* alter hook in drupal_mail() would have been {$module}_{$key}.
* @return MailSystemInterface
*/
function drupal_mail_system($module, $key) {
$instances = &drupal_static(__FUNCTION__, array());
......
......@@ -127,8 +127,8 @@ public function setCountQuery(SelectQueryInterface $query) {
* The count query may be specified manually or, by default, taken from the
* query we are extending.
*
* @return
* A count SelectQueryInterface object.
* @return SelectQueryInterface
* A count query object.
*/
protected function getCountQuery() {
if ($this->customCountQuery) {
......
......@@ -37,6 +37,8 @@ public function __construct(SelectQueryInterface $query, DatabaseConnection $con
* @see theme_table()
* @param $header
* Table header array.
* @return SelectQueryInterface
* The called object.
*/
public function orderByHeader(Array $header) {
$this->header = $header;
......
......@@ -8,7 +8,7 @@
* Normally, the FileTransfer is provided when the site owner is redirected to
* authorize.php as part of a multistep process.
*/
/**
* Interface for a class which can update a Drupal project.
*
......@@ -36,7 +36,8 @@ public function isInstalled();
public static function getProjectName($directory);
/**
* @return string an absolute path to the default install location.
* @return string
* An absolute path to the default install location.
*/
public function getInstallDirectory();
......@@ -71,7 +72,7 @@ class Updater {
* @var string $source Directory to install from.
*/
public $source;
public function __construct($source) {
$this->source = $source;
$this->name = self::getProjectName($source);
......@@ -87,7 +88,7 @@ public function __construct($source) {
* @param string $source
* Directory of a Drupal project.
*
* @return object Updater
* @return Updater
*/
public static function factory($source) {
if (is_dir($source)) {
......@@ -214,7 +215,7 @@ public function update(&$filetransfer, $overrides = array()) {
if ($args['make_backup']) {
$this->makeBackup($args['install_dir'], $args['backup_dir']);
}
if (!$this->name) {
// This is bad, don't want to delete the install directory.
throw new UpdaterException(t('Fatal error in update, cowardly refusing to wipe out the install directory.'));
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment