From 1b01b241aeec9fd7688a8263cbb00a972e894652 Mon Sep 17 00:00:00 2001 From: Dries Buytaert Date: Fri, 4 Dec 2009 16:31:04 +0000 Subject: - Patch #648744 by Crell: specified more @return type definitions for auto-completion in IDEs. --- includes/archiver.inc | 6 ++--- includes/cache.inc | 2 ++ includes/database/database.inc | 40 ++++++++++++++--------------- includes/database/prefetch.inc | 2 +- includes/database/query.inc | 46 ++++++++++++++++++---------------- includes/database/schema.inc | 2 +- includes/database/select.inc | 21 +++++++++------- includes/filetransfer/filetransfer.inc | 15 +++++------ includes/filetransfer/ftp.inc | 8 +++--- includes/mail.inc | 3 ++- includes/pager.inc | 4 +-- includes/tablesort.inc | 2 ++ includes/updater.inc | 11 ++++---- 13 files changed, 88 insertions(+), 74 deletions(-) diff --git a/includes/archiver.inc b/includes/archiver.inc index caf0a0ca0..6b726891e 100644 --- a/includes/archiver.inc +++ b/includes/archiver.inc @@ -27,7 +27,7 @@ interface ArchiverInterface { * @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 @@ interface ArchiverInterface { * * @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 @@ interface ArchiverInterface { * 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()); diff --git a/includes/cache.inc b/includes/cache.inc index 8eb1573b3..7ebfb380e 100644 --- a/includes/cache.inc +++ b/includes/cache.inc @@ -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 diff --git a/includes/database/database.inc b/includes/database/database.inc index 33fa0fb7b..4b1cff0f6 100644 --- a/includes/database/database.inc +++ b/includes/database/database.inc @@ -446,7 +446,7 @@ abstract class DatabaseConnection extends PDO { * 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 @@ abstract class DatabaseConnection extends PDO { /** * 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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * 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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * @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 @@ abstract class DatabaseConnection extends PDO { * * 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 @@ abstract class DatabaseConnection extends PDO { $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 @@ abstract class DatabaseConnection extends PDO { // 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 @@ abstract class DatabaseConnection extends PDO { // Reset any scheduled rollback. $this->willRollback = FALSE; - + // Reset the error logs. $this->rollbackLogs = array(); } @@ -1015,7 +1015,7 @@ abstract class DatabaseConnection extends PDO { * 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) { diff --git a/includes/database/prefetch.inc b/includes/database/prefetch.inc index 73608b82e..663927af7 100644 --- a/includes/database/prefetch.inc +++ b/includes/database/prefetch.inc @@ -221,7 +221,7 @@ class DatabaseStatementPrefetch implements Iterator, DatabaseStatementInterface * The query. * @param array $args * An array of arguments. - * @return + * @return PDOStatement * A PDOStatement object. */ protected function getStatement($query, &$args = array()) { diff --git a/includes/database/query.inc b/includes/database/query.inc index 1418fc809..50c106c0d 100644 --- a/includes/database/query.inc +++ b/includes/database/query.inc @@ -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 @@ interface QueryConditionInterface { * 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 @@ interface QueryConditionInterface { * * @param $field * The name of the field to check. - * @return + * @return QueryConditionInterface * The called object. */ public function isNull($field); @@ -66,7 +66,7 @@ interface QueryConditionInterface { * * @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 @@ interface QueryAlterableInterface { * 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 @@ interface QueryAlterableInterface { * 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 @@ class InsertQuery extends Query { * @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 @@ class InsertQuery extends Query { * * @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 @@ class InsertQuery extends Query { * @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 @@ class InsertQuery extends Query { * * @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 @@ class MergeQuery extends Query { * @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 @@ class MergeQuery extends Query { * @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 @@ class MergeQuery extends Query { * @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 @@ class MergeQuery extends Query { * 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 @@ class MergeQuery extends Query { * @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 @@ class UpdateQuery extends Query implements QueryConditionInterface { * @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 @@ class UpdateQuery extends Query implements QueryConditionInterface { * @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 @@ class DatabaseCondition implements QueryConditionInterface, Countable { /** * 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() { diff --git a/includes/database/schema.inc b/includes/database/schema.inc index 0bd8147f9..61f698685 100644 --- a/includes/database/schema.inc +++ b/includes/database/schema.inc @@ -183,7 +183,7 @@ abstract class DatabaseSchema implements QueryPlaceholderInterface { * 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 = '=') { diff --git a/includes/database/select.inc b/includes/database/select.inc index cda2055ee..84a01f294 100644 --- a/includes/database/select.inc +++ b/includes/database/select.inc @@ -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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * * @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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * 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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * 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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * * for an example of such an alternate sorting mechanism. * - * @return + * @return SelectQueryInterface * The called object */ public function orderRandom(); @@ -380,7 +380,7 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * 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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * @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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn * * @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 @@ interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableIn /** * 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(); diff --git a/includes/filetransfer/filetransfer.inc b/includes/filetransfer/filetransfer.inc index f9182497b..cdd6e2cbf 100644 --- a/includes/filetransfer/filetransfer.inc +++ b/includes/filetransfer/filetransfer.inc @@ -27,10 +27,11 @@ abstract class FileTransfer { 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 @@ abstract class FileTransfer { $this->checkPath($path); $this->chmodJailed($path, $mode, $recursive); } - + /** * Creates a directory. * @@ -156,7 +157,7 @@ abstract class FileTransfer { * @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 @@ abstract class FileTransfer { * 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. diff --git a/includes/filetransfer/ftp.inc b/includes/filetransfer/ftp.inc index e4d83bcc9..d392e16cb 100644 --- a/includes/filetransfer/ftp.inc +++ b/includes/filetransfer/ftp.inc @@ -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 @@ abstract class FileTransferFTP extends FileTransfer { * * @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 @@ abstract class FileTransferFTP extends FileTransfer { 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 @@ abstract class FileTransferFTP extends FileTransfer { * 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)) { diff --git a/includes/mail.inc b/includes/mail.inc index 6b2d3c229..2a2541265 100644 --- a/includes/mail.inc +++ b/includes/mail.inc @@ -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()); diff --git a/includes/pager.inc b/includes/pager.inc index 54616ea33..211fe9a76 100644 --- a/includes/pager.inc +++ b/includes/pager.inc @@ -127,8 +127,8 @@ class PagerDefault extends SelectQueryExtender { * 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) { diff --git a/includes/tablesort.inc b/includes/tablesort.inc index d83e575a0..93ed0f37e 100644 --- a/includes/tablesort.inc +++ b/includes/tablesort.inc @@ -37,6 +37,8 @@ class TableSort extends SelectQueryExtender { * @see theme_table() * @param $header * Table header array. + * @return SelectQueryInterface + * The called object. */ public function orderByHeader(Array $header) { $this->header = $header; diff --git a/includes/updater.inc b/includes/updater.inc index e11f8e1af..76a04ccc9 100644 --- a/includes/updater.inc +++ b/includes/updater.inc @@ -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 @@ interface DrupalUpdaterInterface { 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 @@ class Updater { * @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 @@ class Updater { 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.')); -- cgit v1.2.3