From b883e8c7c06d6f9bc0452ec74caf3be229ece3f1 Mon Sep 17 00:00:00 2001 From: umherirrender Date: Thu, 24 Jul 2014 19:43:03 +0200 Subject: [PATCH] Cleanup some docs (includes/[e-l]) - Swap "$variable type" to "type $variable" - Added missing types - Fixed spacing inside docs - Makes beginning of @param/@return/@var/@throws in capital - Changed some types to match the more common spelling Change-Id: I41a84e8e1dec39170aa655250325ffc485eaeaef --- includes/exception/BadTitleError.php | 2 +- includes/exception/ErrorPageError.php | 2 +- includes/externalstore/ExternalStore.php | 2 +- includes/filebackend/FSFile.php | 2 +- includes/filebackend/FSFileBackend.php | 4 ++-- includes/filebackend/FileBackendStore.php | 2 +- includes/filebackend/SwiftFileBackend.php | 2 +- .../filebackend/filejournal/FileJournal.php | 4 ++-- .../lockmanager/LockManagerGroup.php | 2 +- .../lockmanager/MemcLockManager.php | 2 +- .../lockmanager/RedisLockManager.php | 2 +- includes/filerepo/FileRepo.php | 2 +- includes/filerepo/LocalRepo.php | 2 +- includes/filerepo/RepoGroup.php | 6 +++--- includes/filerepo/file/ArchivedFile.php | 4 ++-- includes/filerepo/file/File.php | 14 ++++++------- includes/filerepo/file/LocalFile.php | 12 +++++------ includes/filerepo/file/OldLocalFile.php | 4 ++-- includes/gallery/PackedImageGallery.php | 2 +- includes/htmlform/HTMLForm.php | 16 +++++++-------- includes/htmlform/HTMLFormField.php | 8 ++++---- includes/installer/Installer.php | 4 ++-- includes/installer/WebInstaller.php | 2 +- includes/installer/WebInstallerPage.php | 2 +- includes/interwiki/Interwiki.php | 4 ++-- includes/jobqueue/Job.php | 2 +- includes/jobqueue/jobs/DuplicateJob.php | 2 +- includes/jobqueue/jobs/NullJob.php | 2 +- includes/jobqueue/jobs/UploadFromUrlJob.php | 4 ++-- includes/logging/LogFormatter.php | 11 +++++----- includes/logging/LogPage.php | 20 +++++++++---------- 31 files changed, 74 insertions(+), 75 deletions(-) diff --git a/includes/exception/BadTitleError.php b/includes/exception/BadTitleError.php index 2da37752f0..e62f8bd6fa 100644 --- a/includes/exception/BadTitleError.php +++ b/includes/exception/BadTitleError.php @@ -29,7 +29,7 @@ class BadTitleError extends ErrorPageError { /** * @param string|Message $msg A message key (default: 'badtitletext') - * @param array $params parameter to wfMessage() + * @param array $params Parameter to wfMessage() */ public function __construct( $msg = 'badtitletext', $params = array() ) { parent::__construct( 'badtitle', $msg, $params ); diff --git a/includes/exception/ErrorPageError.php b/includes/exception/ErrorPageError.php index 7cd198b180..3631a3405c 100644 --- a/includes/exception/ErrorPageError.php +++ b/includes/exception/ErrorPageError.php @@ -32,7 +32,7 @@ class ErrorPageError extends MWException { * * @param string|Message $title Message key (string) for page title, or a Message object * @param string|Message $msg Message key (string) for error text, or a Message object - * @param array $params with parameters to wfMessage() + * @param array $params Array with parameters to wfMessage() */ public function __construct( $title, $msg, $params = array() ) { $this->title = $title; diff --git a/includes/externalstore/ExternalStore.php b/includes/externalstore/ExternalStore.php index 9e09b222b0..688130e03f 100644 --- a/includes/externalstore/ExternalStore.php +++ b/includes/externalstore/ExternalStore.php @@ -178,7 +178,7 @@ class ExternalStore { * itself. It also fails-over to the next possible clusters * as provided in the first parameter. * - * @param array $tryStores refer to $wgDefaultExternalStore + * @param array $tryStores Refer to $wgDefaultExternalStore * @param string $data * @param array $params Associative array of ExternalStoreMedium parameters * @return string|bool The URL of the stored data item, or false on error diff --git a/includes/filebackend/FSFile.php b/includes/filebackend/FSFile.php index 4575e7c56c..29fa875d59 100644 --- a/includes/filebackend/FSFile.php +++ b/includes/filebackend/FSFile.php @@ -237,7 +237,7 @@ class FSFile { /** * Get an associative array containing information about a file in the local filesystem. * - * @param string $path absolute local filesystem path + * @param string $path Absolute local filesystem path * @param mixed $ext The file extension, or true to extract it from the filename. * Set it to false to ignore the extension. * @return array diff --git a/includes/filebackend/FSFileBackend.php b/includes/filebackend/FSFileBackend.php index 2b0c3c224b..b99ffb62e9 100644 --- a/includes/filebackend/FSFileBackend.php +++ b/includes/filebackend/FSFileBackend.php @@ -828,7 +828,7 @@ abstract class FSFileBackendList implements Iterator { protected $params = array(); /** - * @param string $dir file system directory + * @param string $dir File system directory * @param array $params */ public function __construct( $dir, array $params ) { @@ -849,7 +849,7 @@ abstract class FSFileBackendList implements Iterator { /** * Return an appropriate iterator object to wrap * - * @param string $dir file system directory + * @param string $dir File system directory * @return Iterator */ protected function initIterator( $dir ) { diff --git a/includes/filebackend/FileBackendStore.php b/includes/filebackend/FileBackendStore.php index 631d9498fb..495ac3c00b 100644 --- a/includes/filebackend/FileBackendStore.php +++ b/includes/filebackend/FileBackendStore.php @@ -1819,7 +1819,7 @@ abstract class FileBackendStore extends FileBackend { * @param string $storagePath * @param string|null $content File data * @param string|null $fsPath File system path - * @return MIME type + * @return string MIME type */ protected function getContentType( $storagePath, $content, $fsPath ) { return call_user_func_array( $this->mimeCallback, func_get_args() ); diff --git a/includes/filebackend/SwiftFileBackend.php b/includes/filebackend/SwiftFileBackend.php index 9af53c3582..e9c8883d3d 100644 --- a/includes/filebackend/SwiftFileBackend.php +++ b/includes/filebackend/SwiftFileBackend.php @@ -1791,7 +1791,7 @@ abstract class SwiftFileBackendList implements Iterator { * * @param string $container Resolved container name * @param string $dir Resolved path relative to container - * @param string $after null + * @param string $after * @param int $limit * @param array $params * @return Traversable|array diff --git a/includes/filebackend/filejournal/FileJournal.php b/includes/filebackend/filejournal/FileJournal.php index 20c7c354e0..c06514858f 100644 --- a/includes/filebackend/filejournal/FileJournal.php +++ b/includes/filebackend/filejournal/FileJournal.php @@ -132,7 +132,7 @@ abstract class FileJournal { /** * Get the position ID of the latest journal entry at some point in time * - * @param int|string $time timestamp + * @param int|string $time Timestamp * @return int|bool */ final public function getPositionAtTime( $time ) { @@ -224,7 +224,7 @@ class NullFileJournal extends FileJournal { /** * @see FileJournal::doGetPositionAtTime() - * @param int|string $time timestamp + * @param int|string $time Timestamp * @return int|bool */ protected function doGetPositionAtTime( $time ) { diff --git a/includes/filebackend/lockmanager/LockManagerGroup.php b/includes/filebackend/lockmanager/LockManagerGroup.php index ecf396af22..19fc4fef43 100644 --- a/includes/filebackend/lockmanager/LockManagerGroup.php +++ b/includes/filebackend/lockmanager/LockManagerGroup.php @@ -34,7 +34,7 @@ class LockManagerGroup { protected $domain; // string; domain (usually wiki ID) - /** @var array of (name => ('class' => ..., 'config' => ..., 'instance' => ...)) */ + /** @var array Array of (name => ('class' => ..., 'config' => ..., 'instance' => ...)) */ protected $managers = array(); /** diff --git a/includes/filebackend/lockmanager/MemcLockManager.php b/includes/filebackend/lockmanager/MemcLockManager.php index f7ffb2de43..9bb01c218d 100644 --- a/includes/filebackend/lockmanager/MemcLockManager.php +++ b/includes/filebackend/lockmanager/MemcLockManager.php @@ -49,7 +49,7 @@ class MemcLockManager extends QuorumLockManager { /** @var array (server name => bool) */ protected $serversUp = array(); - /** @var string random UUID */ + /** @var string Random UUID */ protected $session = ''; /** diff --git a/includes/filebackend/lockmanager/RedisLockManager.php b/includes/filebackend/lockmanager/RedisLockManager.php index ff4cba56ce..90e058177d 100644 --- a/includes/filebackend/lockmanager/RedisLockManager.php +++ b/includes/filebackend/lockmanager/RedisLockManager.php @@ -51,7 +51,7 @@ class RedisLockManager extends QuorumLockManager { /** @var array Map server names to hostname/IP and port numbers */ protected $lockServers = array(); - /** @var string random UUID */ + /** @var string Random UUID */ protected $session = ''; /** diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php index 8598005041..a45fb7a2bd 100644 --- a/includes/filerepo/FileRepo.php +++ b/includes/filerepo/FileRepo.php @@ -1055,7 +1055,7 @@ class FileRepo { * Returns a FileRepoStatus object with the file Virtual URL in the value, * file can later be disposed using FileRepo::freeTemp(). * - * @param string $originalName the base name of the file as specified + * @param string $originalName The base name of the file as specified * by the user. The file extension will be maintained. * @param string $srcPath The current location of the file. * @return FileRepoStatus Object with the URL in the value. diff --git a/includes/filerepo/LocalRepo.php b/includes/filerepo/LocalRepo.php index 3f7adb0055..96c8803c85 100644 --- a/includes/filerepo/LocalRepo.php +++ b/includes/filerepo/LocalRepo.php @@ -369,7 +369,7 @@ class LocalRepo extends FileRepo { * Get an array or iterator of file objects for files that have a given * SHA-1 content hash. * - * @param string $hash a sha1 hash to look for + * @param string $hash A sha1 hash to look for * @return array */ function findBySha1( $hash ) { diff --git a/includes/filerepo/RepoGroup.php b/includes/filerepo/RepoGroup.php index 65637df9e9..fce3f7854b 100644 --- a/includes/filerepo/RepoGroup.php +++ b/includes/filerepo/RepoGroup.php @@ -272,7 +272,7 @@ class RepoGroup { /** * Find all instances of files with this key * - * @param string $hash base 36 SHA-1 hash + * @param string $hash Base 36 SHA-1 hash * @return array Array of File objects */ function findBySha1( $hash ) { @@ -292,7 +292,7 @@ class RepoGroup { /** * Find all instances of files with this keys * - * @param array $hashes base 36 SHA-1 hashes + * @param array $hashes Base 36 SHA-1 hashes * @return array Array of array of File objects */ function findBySha1s( array $hashes ) { @@ -420,7 +420,7 @@ class RepoGroup { * Split a virtual URL into repo, zone and rel parts * @param string $url * @throws MWException - * @return array containing repo, zone and rel + * @return array Containing repo, zone and rel */ function splitVirtualUrl( $url ) { if ( substr( $url, 0, 9 ) != 'mwrepo://' ) { diff --git a/includes/filerepo/file/ArchivedFile.php b/includes/filerepo/file/ArchivedFile.php index 1eee6a23bf..735bf8a555 100644 --- a/includes/filerepo/file/ArchivedFile.php +++ b/includes/filerepo/file/ArchivedFile.php @@ -27,7 +27,7 @@ * @ingroup FileAbstraction */ class ArchivedFile { - /** @var int filearchive row ID */ + /** @var int Filearchive row ID */ private $id; /** @var string File name */ @@ -42,7 +42,7 @@ class ArchivedFile { /** @var int File size in bytes */ private $size; - /** @var int size in bytes */ + /** @var int Size in bytes */ private $bits; /** @var int Width */ diff --git a/includes/filerepo/file/File.php b/includes/filerepo/file/File.php index 260fde1198..32374cdeaa 100644 --- a/includes/filerepo/file/File.php +++ b/includes/filerepo/file/File.php @@ -127,7 +127,7 @@ abstract class File { /** @var string Relative path including trailing slash */ protected $hashPath; - /** @var string number of pages of a multipage document, or false for + /** @var string Number of pages of a multipage document, or false for * documents which aren't multipage documents */ protected $pageCount; @@ -583,7 +583,7 @@ abstract class File { * * Currently used to add a warning to the image description page * - * @return bool false if the main image is both animated + * @return bool False if the main image is both animated * and the thumbnail is not. In all other cases must return * true. If image is not renderable whatsoever, should * return true. @@ -1189,7 +1189,7 @@ abstract class File { /** * Returns the most appropriate source image for the thumbnail, given a target thumbnail size * @param array $params - * @return array source path and width/height of the source + * @return array Source path and width/height of the source */ public function getThumbnailSource( $params ) { if ( $this->repo @@ -1606,7 +1606,7 @@ abstract class File { * * @param string $zone Name of requested zone * @param bool|string $suffix If not false, the name of a file in zone - * @return string path + * @return string Path */ function getZoneUrl( $zone, $suffix = false ) { $this->assertRepoDefined(); @@ -1623,7 +1623,7 @@ abstract class File { * Get the URL of the thumbnail directory, or a particular file if $suffix is specified * * @param bool|string $suffix If not false, the name of a thumbnail file - * @return string path + * @return string Path */ function getThumbUrl( $suffix = false ) { return $this->getZoneUrl( 'thumb', $suffix ); @@ -1633,7 +1633,7 @@ abstract class File { * Get the URL of the transcoded directory, or a particular file if $suffix is specified * * @param bool|string $suffix If not false, the name of a media file - * @return string path + * @return string Path */ function getTranscodedUrl( $suffix = false ) { return $this->getZoneUrl( 'transcoded', $suffix ); @@ -1741,7 +1741,7 @@ abstract class File { * @param int $flags A bitwise combination of: * File::DELETE_SOURCE Delete the source file, i.e. move rather than copy * @param array $options Optional additional parameters - * @return FileRepoStatus object. On success, the value member contains the + * @return FileRepoStatus On success, the value member contains the * archive name, or an empty string if it was a new file. * * STUB diff --git a/includes/filerepo/file/LocalFile.php b/includes/filerepo/file/LocalFile.php index 1f2defec72..1eff1dfec4 100644 --- a/includes/filerepo/file/LocalFile.php +++ b/includes/filerepo/file/LocalFile.php @@ -49,10 +49,10 @@ class LocalFile extends File { /** @var bool Does the file exist on disk? (loadFromXxx) */ protected $fileExists; - /** @var int image width */ + /** @var int Image width */ protected $width; - /** @var int image height */ + /** @var int Image height */ protected $height; /** @var int Returned by getimagesize (loadFromXxx) */ @@ -166,7 +166,7 @@ class LocalFile extends File { * Create a LocalFile from a SHA-1 key * Do not call this except from inside a repo class. * - * @param string $sha1 base-36 SHA-1 + * @param string $sha1 Base-36 SHA-1 * @param LocalRepo $repo * @param string|bool $timestamp MW_timestamp (optional) * @return bool|LocalFile @@ -437,7 +437,7 @@ class LocalFile extends File { /** * @param DatabaseBase $dbr * @param string $fname - * @return array|false + * @return array|bool */ private function loadFieldsWithTimestamp( $dbr, $fname ) { $fieldMap = false; @@ -833,7 +833,7 @@ class LocalFile extends File { /** * Get all thumbnail names previously generated for this file * @param string|bool $archiveName Name of an archive file, default false - * @return array first element is the base dir, then files in that base dir. + * @return array First element is the base dir, then files in that base dir. */ function getThumbnails( $archiveName = false ) { if ( $archiveName ) { @@ -1848,7 +1848,7 @@ class LocalFile extends File { * Start a transaction and lock the image for update * Increments a reference counter if the lock is already held * @throws MWException Throws an error if the lock was not acquired - * @return bool success + * @return bool Success */ function lock() { $dbw = $this->repo->getMasterDB(); diff --git a/includes/filerepo/file/OldLocalFile.php b/includes/filerepo/file/OldLocalFile.php index ca9249654f..0adcc73c62 100644 --- a/includes/filerepo/file/OldLocalFile.php +++ b/includes/filerepo/file/OldLocalFile.php @@ -79,7 +79,7 @@ class OldLocalFile extends LocalFile { * Create a OldLocalFile from a SHA-1 key * Do not call this except from inside a repo class. * - * @param string $sha1 base-36 SHA-1 + * @param string $sha1 Base-36 SHA-1 * @param LocalRepo $repo * @param string|bool $timestamp MW_timestamp (optional) * @@ -130,7 +130,7 @@ class OldLocalFile extends LocalFile { * @param Title $title * @param FileRepo $repo * @param string $time Timestamp or null to load by archive name - * @param string $archiveName archive name or null to load by timestamp + * @param string $archiveName Archive name or null to load by timestamp * @throws MWException */ function __construct( $title, $repo, $time, $archiveName ) { diff --git a/includes/gallery/PackedImageGallery.php b/includes/gallery/PackedImageGallery.php index bb55c89e9e..b004a9529e 100644 --- a/includes/gallery/PackedImageGallery.php +++ b/includes/gallery/PackedImageGallery.php @@ -76,7 +76,7 @@ class PackedImageGallery extends TraditionalImageGallery { } /** - * @param MediaTransformOutput|bool $thumb the thumbnail, or false if no + * @param MediaTransformOutput|bool $thumb The thumbnail, or false if no * thumb (which can happen) * @return float */ diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php index df6582c7b2..d7c5d7f52a 100644 --- a/includes/htmlform/HTMLForm.php +++ b/includes/htmlform/HTMLForm.php @@ -352,7 +352,7 @@ class HTMLForm extends ContextSource { * @param array $descriptor Input Descriptor, as described above * * @throws MWException - * @return HTMLFormField subclass + * @return HTMLFormField Instance of a subclass of HTMLFormField */ public static function loadInputFromParameters( $fieldname, $descriptor ) { $class = self::getClassFromDescriptor( $fieldname, $descriptor ); @@ -622,7 +622,7 @@ class HTMLForm extends ContextSource { /** * Add footer text, inside the form. * - * @param string $msg complete text of message to display + * @param string $msg Complete text of message to display * @param string|null $section The section to add the footer text to * * @return HTMLForm $this for chaining calls (since 1.20) @@ -741,8 +741,8 @@ class HTMLForm extends ContextSource { * Only useful when the method is "post". * * @since 1.24 - * @param string|array Salt to use - * @return HTMLForm $this for chaining calls + * @param string|array $salt Salt to use + * @return HTMLForm $this For chaining calls */ public function setTokenSalt( $salt ) { $this->mTokenSalt = $salt; @@ -760,7 +760,7 @@ class HTMLForm extends ContextSource { * * @param bool|string|array|Status $submitResult Output from HTMLForm::trySubmit() * - * @return Nothing, should be last call + * @return void Nothing, should be last call */ function displayForm( $submitResult ) { $this->getOutput()->addHTML( $this->getHTML( $submitResult ) ); @@ -980,7 +980,7 @@ class HTMLForm extends ContextSource { /** * Format a stack of error messages into a single HTML string * - * @param array $errors of message keys/values + * @param array $errors Array of message keys/values * * @return string HTML, a "