From c052fc3b7b7142a2e1c556026604e27984fb601b Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Fri, 10 Feb 2012 15:37:33 +0000 Subject: [PATCH] Documentation followups from lastnight --- includes/Article.php | 2 +- includes/ChangesList.php | 2 +- includes/ExternalUser.php | 2 +- includes/HTMLForm.php | 2 +- includes/Hooks.php | 2 +- includes/Import.php | 2 +- includes/MagicWord.php | 4 +-- includes/Title.php | 1 - includes/User.php | 2 +- includes/WebRequest.php | 2 +- includes/WikiPage.php | 4 +-- includes/cache/MessageCache.php | 2 +- includes/db/DatabaseMysql.php | 2 +- includes/db/DatabaseSqlite.php | 6 ++-- includes/db/LoadBalancer.php | 2 +- includes/diff/DairikiDiff.php | 2 +- includes/filerepo/FileRepo.php | 12 +++---- includes/filerepo/backend/FileBackend.php | 2 +- includes/filerepo/backend/FileOp.php | 2 +- .../filerepo/backend/SwiftFileBackend.php | 2 +- includes/filerepo/file/ArchivedFile.php | 2 +- includes/filerepo/file/File.php | 32 +++++++++---------- includes/filerepo/file/LocalFile.php | 2 +- includes/media/Generic.php | 4 +-- includes/parser/ParserCache.php | 4 +-- skins/MonoBook.php | 7 ++++ skins/Vector.php | 6 ++++ 27 files changed, 64 insertions(+), 50 deletions(-) diff --git a/includes/Article.php b/includes/Article.php index 636115543a..99997c86b1 100644 --- a/includes/Article.php +++ b/includes/Article.php @@ -1582,7 +1582,7 @@ class Article extends Page { /** * Get parser options suitable for rendering the primary article wikitext - * @return ParserOptions|bool + * @return ParserOptions */ public function getParserOptions() { global $wgUser; diff --git a/includes/ChangesList.php b/includes/ChangesList.php index 8a1f375285..4611611d23 100644 --- a/includes/ChangesList.php +++ b/includes/ChangesList.php @@ -63,7 +63,7 @@ class ChangesList extends ContextSource { * This first argument used to be an User object. * * @deprecated in 1.18; use newFromContext() instead - * @param $unused + * @param $unused string|User Unused * @return ChangesList|EnhancedChangesList|OldChangesList derivative */ public static function newFromUser( $unused ) { diff --git a/includes/ExternalUser.php b/includes/ExternalUser.php index 49d525f883..bea0e7e19b 100644 --- a/includes/ExternalUser.php +++ b/includes/ExternalUser.php @@ -98,7 +98,7 @@ abstract class ExternalUser { * This is a wrapper around newFromId(). * * @param $user User - * @return ExternalUser|bool + * @return ExternalUser|bool False on failure */ public static function newFromUser( $user ) { global $wgExternalAuthType; diff --git a/includes/HTMLForm.php b/includes/HTMLForm.php index ad349090d0..e9f04c14cb 100644 --- a/includes/HTMLForm.php +++ b/includes/HTMLForm.php @@ -664,7 +664,7 @@ class HTMLForm extends ContextSource { /** * Get the text for the submit button, either customised or a default. - * @return + * @return string */ function getSubmitText() { return $this->mSubmitText diff --git a/includes/Hooks.php b/includes/Hooks.php index 54c18fd4f8..bc39f2fc25 100644 --- a/includes/Hooks.php +++ b/includes/Hooks.php @@ -259,7 +259,7 @@ class Hooks { /** * This REALLY should be protected... but it's public for compatibility * - * @param $errno + * @param $errno int Unused * @param $errstr String: error message * @return Boolean: false */ diff --git a/includes/Import.php b/includes/Import.php index 497f46ca82..d53302bb18 100644 --- a/includes/Import.php +++ b/includes/Import.php @@ -301,7 +301,7 @@ class WikiImporter { /** * Notify the callback function of a revision - * @param $revision |WikiRevision object + * @param $revision WikiRevision object * @return bool|mixed */ private function revisionCallback( $revision ) { diff --git a/includes/MagicWord.php b/includes/MagicWord.php index 14ca4a0425..941d97fc54 100644 --- a/includes/MagicWord.php +++ b/includes/MagicWord.php @@ -813,7 +813,7 @@ class MagicWordArray { * * @param $text string * - * @return string|bool + * @return string|bool False on failure */ public function matchStartToEnd( $text ) { $hash = $this->getHash(); @@ -861,7 +861,7 @@ class MagicWordArray { * * @param $text string * - * @return int|bool + * @return int|bool False on failure */ public function matchStartAndRemove( &$text ) { $regexes = $this->getRegexStart(); diff --git a/includes/Title.php b/includes/Title.php index fe96ecdfaa..0ef4cda26b 100644 --- a/includes/Title.php +++ b/includes/Title.php @@ -261,7 +261,6 @@ class Title { * If false is given, the title will be treated as non-existing. * * @param $row Object|bool database row - * @return void */ public function loadFromRow( $row ) { if ( $row ) { // page found diff --git a/includes/User.php b/includes/User.php index 26fb7d61b4..9ac1ef2e3f 100644 --- a/includes/User.php +++ b/includes/User.php @@ -3381,7 +3381,7 @@ class User { * address if it was already confirmed. * * @note Call saveSettings() after calling this function to commit the change. - * @return bool + * @return bool Returns true */ function invalidateEmail() { $this->load(); diff --git a/includes/WebRequest.php b/includes/WebRequest.php index fc41589ab1..826ee0d041 100644 --- a/includes/WebRequest.php +++ b/includes/WebRequest.php @@ -838,7 +838,7 @@ class WebRequest { * Get a request header, or false if it isn't set * @param $name String: case-insensitive header name * - * @return string|bool + * @return string|bool False on failure */ public function getHeader( $name ) { $this->initHeaders(); diff --git a/includes/WikiPage.php b/includes/WikiPage.php index 05401fa294..ea66ab75df 100644 --- a/includes/WikiPage.php +++ b/includes/WikiPage.php @@ -414,7 +414,7 @@ class WikiPage extends Page { * Revision::FOR_PUBLIC to be displayed to all users * Revision::FOR_THIS_USER to be displayed to $wgUser * Revision::RAW get the text regardless of permissions - * @return String|bool The text of the current revision + * @return String|bool The text of the current revision. False on failure */ public function getText( $audience = Revision::FOR_PUBLIC ) { $this->loadLastEdit(); @@ -427,7 +427,7 @@ class WikiPage extends Page { /** * Get the text of the current revision. No side-effects... * - * @return String|bool The text of the current revision + * @return String|bool The text of the current revision. False on failure */ public function getRawText() { $this->loadLastEdit(); diff --git a/includes/cache/MessageCache.php b/includes/cache/MessageCache.php index 424b3fdc89..1d0ab902ed 100644 --- a/includes/cache/MessageCache.php +++ b/includes/cache/MessageCache.php @@ -697,7 +697,7 @@ class MessageCache { * @param $title String: Message cache key with initial uppercase letter. * @param $code String: code denoting the language to try. * - * @return string|bool + * @return string|bool False on failure */ function getMsgFromNamespace( $title, $code ) { global $wgAdaptiveMessageCache; diff --git a/includes/db/DatabaseMysql.php b/includes/db/DatabaseMysql.php index 86681fc237..b4efd56a90 100644 --- a/includes/db/DatabaseMysql.php +++ b/includes/db/DatabaseMysql.php @@ -385,7 +385,7 @@ class DatabaseMysql extends DatabaseBase { * @param $table string * @param $index string * @param $fname string - * @return bool|array + * @return bool|array|null False or null on failure */ function indexInfo( $table, $index, $fname = 'DatabaseMysql::indexInfo' ) { # SHOW INDEX works in MySQL 3.23.58, but SHOW INDEXES does not. diff --git a/includes/db/DatabaseSqlite.php b/includes/db/DatabaseSqlite.php index 169da2b584..05568102dd 100644 --- a/includes/db/DatabaseSqlite.php +++ b/includes/db/DatabaseSqlite.php @@ -140,7 +140,7 @@ class DatabaseSqlite extends DatabaseBase { /** * Check if the searchindext table is FTS enabled. - * @return bool if not enabled. + * @return bool False if not enabled. */ function checkForEnabledSearch() { if ( self::$fulltextEnabled === null ) { @@ -618,7 +618,9 @@ class DatabaseSqlite extends DatabaseBase { * Get information about a given field * Returns false if the field does not exist. * - * @return SQLiteField|bool + * @param $table string + * @param $field string + * @return SQLiteField|bool False on failure */ function fieldInfo( $table, $field ) { $tableName = $this->tableName( $table ); diff --git a/includes/db/LoadBalancer.php b/includes/db/LoadBalancer.php index 5357eb49ba..7f200eae04 100644 --- a/includes/db/LoadBalancer.php +++ b/includes/db/LoadBalancer.php @@ -385,7 +385,7 @@ class LoadBalancer { * Returns false if there is no connection open * * @param $i int - * @return DatabaseBase|bool + * @return DatabaseBase|bool False on failure */ function getAnyOpenConnection( $i ) { foreach ( $this->mConns as $conns ) { diff --git a/includes/diff/DairikiDiff.php b/includes/diff/DairikiDiff.php index b9edc953b3..e7c439313b 100644 --- a/includes/diff/DairikiDiff.php +++ b/includes/diff/DairikiDiff.php @@ -661,7 +661,7 @@ class Diff { * * $diff = new Diff($lines1, $lines2); * $rev = $diff->reverse(); - * @return object object A Diff object representing the inverse of the + * @return Object A Diff object representing the inverse of the * original diff. */ function reverse() { diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php index 4555d4db14..516b44854b 100644 --- a/includes/filerepo/FileRepo.php +++ b/includes/filerepo/FileRepo.php @@ -295,7 +295,7 @@ class FileRepo { * private: If true, return restricted (deleted) files if the current * user is allowed to view them. Otherwise, such files will not * be found. - * @return File|bool + * @return File|bool False on failure */ public function findFile( $title, $options = array() ) { $title = File::normalizeTitle( $title ); @@ -378,7 +378,7 @@ class FileRepo { * * @param $sha1 String base 36 SHA-1 hash * @param $options array Option array, same as findFile(). - * @return File|bool + * @return File|bool False on failure */ public function findFileFromKey( $sha1, $options = array() ) { $time = isset( $options['time'] ) ? $options['time'] : false; @@ -420,7 +420,7 @@ class FileRepo { /** * Get the public root URL of the repository * - * @return string|bool + * @return string */ public function getRootUrl() { return $this->url; @@ -533,7 +533,7 @@ class FileRepo { * * @param $query mixed Query string to append * @param $entry string Entry point; defaults to index - * @return string|bool + * @return string|bool False on failure */ public function makeUrl( $query = '', $entry = 'index' ) { if ( isset( $this->scriptDirUrl ) ) { @@ -613,7 +613,7 @@ class FileRepo { /** * Get the URL of the stylesheet to apply to description pages * - * @return string|bool + * @return string|bool False on failure */ public function getDescriptionStylesheetUrl() { if ( isset( $this->scriptDirUrl ) ) { @@ -1191,7 +1191,7 @@ class FileRepo { * Get the timestamp of a file with a given virtual URL/storage path * * @param $virtualUrl string - * @return string|bool + * @return string|bool False on failure */ public function getFileTimestamp( $virtualUrl ) { $path = $this->resolveToStoragePath( $virtualUrl ); diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php index e1f162c513..c949b00560 100644 --- a/includes/filerepo/backend/FileBackend.php +++ b/includes/filerepo/backend/FileBackend.php @@ -1179,7 +1179,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackend::getFileSha1Base36() - * @return bool + * @return bool|string */ final public function getFileSha1Base36( array $params ) { wfProfileIn( __METHOD__ ); diff --git a/includes/filerepo/backend/FileOp.php b/includes/filerepo/backend/FileOp.php index 300d513fb8..bf3535694e 100644 --- a/includes/filerepo/backend/FileOp.php +++ b/includes/filerepo/backend/FileOp.php @@ -324,7 +324,7 @@ abstract class FileOp { * * @param $source string Storage path * @param $predicates Array - * @return string|bool + * @return string|bool False on failure */ final protected function fileSha1( $source, array $predicates ) { if ( isset( $predicates['sha1'][$source] ) ) { diff --git a/includes/filerepo/backend/SwiftFileBackend.php b/includes/filerepo/backend/SwiftFileBackend.php index fa7a409ac2..e2c5986801 100644 --- a/includes/filerepo/backend/SwiftFileBackend.php +++ b/includes/filerepo/backend/SwiftFileBackend.php @@ -708,7 +708,7 @@ class SwiftFileBackend extends FileBackendStore { /** * Get a connection to the Swift proxy * - * @return CF_Connection|bool + * @return CF_Connection|bool False on failure * @throws InvalidResponseException */ protected function getConnection() { diff --git a/includes/filerepo/file/ArchivedFile.php b/includes/filerepo/file/ArchivedFile.php index 2b43273fb9..9b0844b6fa 100644 --- a/includes/filerepo/file/ArchivedFile.php +++ b/includes/filerepo/file/ArchivedFile.php @@ -93,7 +93,7 @@ class ArchivedFile { /** * Loads a file object from the filearchive table - * @return bool on success or null + * @return bool|null True on success or null */ public function load() { if ( $this->dataLoaded ) { diff --git a/includes/filerepo/file/File.php b/includes/filerepo/file/File.php index 88c8a55b40..543f23fc83 100644 --- a/includes/filerepo/file/File.php +++ b/includes/filerepo/file/File.php @@ -73,14 +73,14 @@ abstract class File { var $repo; /** - * @var Title|bool + * @var Title */ var $title; var $lastError, $redirected, $redirectedTitle; /** - * @var FSFile|bool + * @var FSFile|bool False if undefined */ protected $fsFile; @@ -252,7 +252,7 @@ abstract class File { /** * Return the associated title object * - * @return Title|bool + * @return Title */ public function getTitle() { return $this->title; @@ -319,17 +319,17 @@ abstract class File { } /** - * Return the storage path to the file. Note that this does - * not mean that a file actually exists under that location. - * - * This path depends on whether directory hashing is active or not, - * i.e. whether the files are all found in the same directory, - * or in hashed paths like /images/3/3c. - * - * Most callers don't check the return value, but ForeignAPIFile::getPath - * returns false. + * Return the storage path to the file. Note that this does + * not mean that a file actually exists under that location. + * + * This path depends on whether directory hashing is active or not, + * i.e. whether the files are all found in the same directory, + * or in hashed paths like /images/3/3c. + * + * Most callers don't check the return value, but ForeignAPIFile::getPath + * returns false. * - * @return string|bool + * @return string|bool ForeignAPIFile::getPath can return false */ public function getPath() { if ( !isset( $this->path ) ) { @@ -344,7 +344,7 @@ abstract class File { * Returns false on failure. Callers must not alter the file. * Temporary files are cleared automatically. * - * @return string|bool + * @return string|bool False on failure */ public function getLocalRefPath() { $this->assertRepoDefined(); @@ -383,7 +383,7 @@ abstract class File { * * @param $page int * - * @return bool|number + * @return bool|number False on failure */ public function getHeight( $page = 1 ) { return false; @@ -779,7 +779,7 @@ abstract class File { * @param $params Array: an associative array of handler-specific parameters. * Typical keys are width, height and page. * @param $flags Integer: a bitfield, may contain self::RENDER_NOW to force rendering - * @return MediaTransformOutput|bool + * @return MediaTransformOutput|bool False on failure */ function transform( $params, $flags = 0 ) { global $wgUseSquid, $wgIgnoreImageErrors, $wgThumbnailEpoch; diff --git a/includes/filerepo/file/LocalFile.php b/includes/filerepo/file/LocalFile.php index d0533184bf..6fbf9c06ba 100644 --- a/includes/filerepo/file/LocalFile.php +++ b/includes/filerepo/file/LocalFile.php @@ -627,7 +627,7 @@ class LocalFile extends File { /** * Get all thumbnail names previously generated for this file - * @param $archiveName string|bool Name of an archive file + * @param $archiveName string|bool Name of an archive file, default false * @return array first element is the base dir, then files in that base dir. */ function getThumbnails( $archiveName = false ) { diff --git a/includes/media/Generic.php b/includes/media/Generic.php index af1ca4d66a..70bc449678 100644 --- a/includes/media/Generic.php +++ b/includes/media/Generic.php @@ -496,7 +496,7 @@ abstract class MediaHandler { * * @param $dstPath string The location of the suspect file * @param $retval int Return value of some shell process, file will be deleted if this is non-zero - * @return bool if removed, false otherwise + * @return bool True if removed, false otherwise */ function removeBadFile( $dstPath, $retval = 0 ) { if( file_exists( $dstPath ) ) { @@ -664,7 +664,7 @@ abstract class ImageHandler extends MediaHandler { * @param $srcWidth Integer: width of the source image * @param $srcHeight Integer: height of the source image * @param $mimeType - * @return bool to indicate that an error should be returned to the user. + * @return bool False to indicate that an error should be returned to the user. */ function validateThumbParams( &$width, &$height, $srcWidth, $srcHeight, $mimeType ) { $width = intval( $width ); diff --git a/includes/parser/ParserCache.php b/includes/parser/ParserCache.php index bde310ef78..a8899cbc2b 100644 --- a/includes/parser/ParserCache.php +++ b/includes/parser/ParserCache.php @@ -89,7 +89,7 @@ class ParserCache { * Retrieve the ParserOutput from ParserCache, even if it's outdated. * @param $article Article * @param $popts ParserOptions - * @return ParserOutput|bool + * @return ParserOutput|bool False on failure */ public function getDirty( $article, $popts ) { $value = $this->get( $article, $popts, true ); @@ -145,7 +145,7 @@ class ParserCache { * @param $popts ParserOptions * @param $useOutdated * - * @return ParserOutput|bool + * @return ParserOutput|bool False on failure */ public function get( $article, $popts, $useOutdated = false ) { global $wgCacheEpoch; diff --git a/skins/MonoBook.php b/skins/MonoBook.php index f1fe509014..857db0f28a 100644 --- a/skins/MonoBook.php +++ b/skins/MonoBook.php @@ -158,6 +158,9 @@ echo $footerEnd; /*************************************************************************************************/ + /** + * @param $sidebar array + */ protected function renderPortals( $sidebar ) { if ( !isset( $sidebar['SEARCH'] ) ) $sidebar['SEARCH'] = true; if ( !isset( $sidebar['TOOLBOX'] ) ) $sidebar['TOOLBOX'] = true; @@ -265,6 +268,10 @@ echo $footerEnd; } /*************************************************************************************************/ + /** + * @param $bar string + * @param $cont array|string + */ function customBox( $bar, $cont ) { $portletAttribs = array( 'class' => 'generated-sidebar portlet', 'id' => Sanitizer::escapeId( "p-$bar" ) ); $tooltip = Linker::titleAttrib( "p-$bar" ); diff --git a/skins/Vector.php b/skins/Vector.php index 4b6433d630..0c7686aef8 100644 --- a/skins/Vector.php +++ b/skins/Vector.php @@ -286,6 +286,12 @@ class VectorTemplate extends BaseTemplate { } } + /** + * @param $name string + * @param $content array + * @param $msg null|string + * @param $hook null|string|array + */ private function renderPortal( $name, $content, $msg = null, $hook = null ) { if ( $msg === null ) { $msg = $name; -- 2.20.1