Cleanup - let's make IDEs more useful

http://phpdoc.org/docs/latest/references/phpdoc/types.html

If IDEs have many warnings, we don't look at them.
Let's minimize the number of warnings, and make them useful again.

* Some function docs fixes
* Removed unused $iwprefixes var in ApiQuerySearch.php
* declared private $blockStatusByUid in SpecialActiveusers
* declared private $repo in UploadFromChunks

Change-Id: Ifd20f78b168b9a913fdb8d89dc26a76a173b1c29

includes/api/ApiPageSet.php

@@ -61,6 +61,7 @@ class ApiPageSet extends ApiBase {
 	private $mSpecialTitles = array();
 	private $mNormalizedTitles = array();
 	private $mInterwikiTitles = array();
+	/** @var Title[] */
 	private $mPendingRedirectIDs = array();
 	private $mConvertedTitles = array();
 	private $mGoodRevIDs = array();
@@ -68,9 +69,7 @@ class ApiPageSet extends ApiBase {
 	private $mFakePageId = -1;
 	private $mCacheMode = 'public';
 	private $mRequestedPageFields = array();
-	/**
-	 * @var int
-	 */
+	/** @var int */
 	private $mDefaultNamespace = NS_MAIN;
 
 	/**
@@ -389,7 +388,7 @@ class ApiPageSet extends ApiBase {
 	/**
 	 * Get a list of redirect resolutions - maps a title to its redirect
 	 * target, as an array of output-ready arrays
-	 * @return array
+	 * @return Title[]
 	 */
 	public function getRedirectTitles() {
 		return $this->mRedirectTitles;
@@ -598,7 +597,7 @@ class ApiPageSet extends ApiBase {
 
 	/**
 	 * Get the list of titles with negative namespace
-	 * @return array Title
+	 * @return Title[]
 	 */
 	public function getSpecialTitles() {
 		return $this->mSpecialTitles;

includes/api/ApiQuerySearch.php

@@ -197,7 +197,6 @@ class ApiQuerySearch extends ApiQueryGeneratorBase {
 		$hasInterwikiResults = false;
 		if ( $interwiki && $resultPageSet === null && $matches->hasInterwikiResults() ) {
 			$matches = $matches->getInterwikiResults();
-			$iwprefixes = array();
 			$hasInterwikiResults = true;
 
 			// Include number of results if requested

includes/api/ApiResult.php

@@ -461,7 +461,7 @@ class ApiResult extends ApiBase {
 	 *
 	 * @since 1.24
 	 * @param string|null $continue The "continue" parameter, if any
-	 * @param array $allModules Contains ApiBase instances that will be executed
+	 * @param ApiBase[] $allModules Contains ApiBase instances that will be executed
 	 * @param array $generatedModules Names of modules that depend on the generator
 	 * @return array Two elements: a boolean indicating if the generator is done,
 	 *   and an array of modules to actually execute.

includes/api/ApiUpload.php

@@ -28,7 +28,7 @@
  * @ingroup API
  */
 class ApiUpload extends ApiBase {
-	/** @var UploadBase */
+	/** @var UploadBase|UploadFromChunks */
 	protected $mUpload = null;
 
 	protected $mParams;
@@ -210,7 +210,6 @@ class ApiUpload extends ApiBase {
 			}
 		} else {
 			$filekey = $this->mParams['filekey'];
-			/** @var $status Status */
 			$status = $this->mUpload->addChunk(
 				$chunkPath, $chunkSize, $this->mParams['offset'] );
 			if ( !$status->isGood() ) {
@@ -551,6 +550,7 @@ class ApiUpload extends ApiBase {
 
 			if ( isset( $warnings['duplicate'] ) ) {
 				$dupes = array();
+				/** @var File $dupe */
 				foreach ( $warnings['duplicate'] as $dupe ) {
 					$dupes[] = $dupe->getName();
 				}
@@ -561,6 +561,7 @@ class ApiUpload extends ApiBase {
 			if ( isset( $warnings['exists'] ) ) {
 				$warning = $warnings['exists'];
 				unset( $warnings['exists'] );
+				/** @var LocalFile $localFile */
 				$localFile = isset( $warning['normalizedFile'] )
 					? $warning['normalizedFile']
 					: $warning['file'];

includes/db/DatabaseUtility.php

@@ -140,7 +140,7 @@ class ResultWrapper implements Iterator {
 	 * Fields can be retrieved with $row->fieldname, with fields acting like
 	 * member variables.
 	 *
-	 * @return object
+	 * @return stdClass
 	 * @throws DBUnexpectedError Thrown if the database returns an error
 	 */
 	function fetchObject() {
@@ -177,8 +177,8 @@ class ResultWrapper implements Iterator {
 		$this->db->dataSeek( $this, $row );
 	}
 
-	/*********************
-	 * Iterator functions
+	/*
+	 * ======= Iterator functions =======
 	 * Note that using these in combination with the non-iterator functions
 	 * above may cause rows to be skipped or repeated.
 	 */
@@ -192,7 +192,7 @@ class ResultWrapper implements Iterator {
 	}
 
 	/**
-	 * @return int
+	 * @return stdClass|array|false
 	 */
 	function current() {
 		if ( is_null( $this->currentRow ) ) {
@@ -210,7 +210,7 @@ class ResultWrapper implements Iterator {
 	}
 
 	/**
-	 * @return int
+	 * @return stdClass
 	 */
 	function next() {
 		$this->pos++;
@@ -255,6 +255,9 @@ class FakeResultWrapper extends ResultWrapper {
 		return count( $this->result );
 	}
 
+	/**
+	 * @return array|bool
+	 */
 	function fetchRow() {
 		if ( $this->pos < count( $this->result ) ) {
 			$this->currentRow = $this->result[$this->pos];
@@ -276,7 +279,10 @@ class FakeResultWrapper extends ResultWrapper {
 	function free() {
 	}
 
-	// Callers want to be able to access fields with $this->fieldName
+	/**
+	 * Callers want to be able to access fields with $this->fieldName
+	 * @return false|stdClass
+	 */
 	function fetchObject() {
 		$this->fetchRow();
 		if ( $this->currentRow ) {
@@ -291,6 +297,9 @@ class FakeResultWrapper extends ResultWrapper {
 		$this->currentRow = null;
 	}
 
+	/**
+	 * @return false|stdClass
+	 */
 	function next() {
 		return $this->fetchObject();
 	}

includes/filerepo/FileRepo.php

@@ -546,7 +546,7 @@ class FileRepo {
 	 *
 	 * STUB
 	 * @param string $hash SHA-1 hash
-	 * @return array
+	 * @return File[]
 	 */
 	public function findBySha1( $hash ) {
 		return array();
@@ -1014,6 +1014,7 @@ class FileRepo {
 			} elseif ( is_array( $triple[2] ) && isset( $triple[2]['headers'] ) ) {
 				$headers = $triple[2]['headers'];
 			}
+			// @fixme: $headers might not be defined
 			$operations[] = array(
 				'op' => FileBackend::isStoragePath( $src ) ? 'copy' : 'store',
 				'src' => $src,

includes/filerepo/LocalRepo.php

@@ -49,7 +49,7 @@ class LocalRepo extends FileRepo {
 
 	/**
 	 * @throws MWException
-	 * @param array $row
+	 * @param stdClass $row
 	 * @return LocalFile
 	 */
 	function newFileFromRow( $row ) {
@@ -91,7 +91,7 @@ class LocalRepo extends FileRepo {
 			$hashPath = $this->getDeletedHashPath( $key );
 			$path = "$root/$hashPath$key";
 			$dbw->begin( __METHOD__ );
-			// Check for usage in deleted/hidden files and pre-emptively
+			// Check for usage in deleted/hidden files and preemptively
 			// lock the key to avoid any future use until we are finished.
 			$deleted = $this->deletedFileHasKey( $key, 'lock' );
 			$hidden = $this->hiddenFileHasKey( $key, 'lock' );
@@ -167,7 +167,7 @@ class LocalRepo extends FileRepo {
 	 * Checks if there is a redirect named as $title
 	 *
 	 * @param Title $title Title of file
-	 * @return bool
+	 * @return bool|Title
 	 */
 	function checkRedirect( Title $title ) {
 		global $wgMemc;
@@ -370,7 +370,7 @@ class LocalRepo extends FileRepo {
 	 * SHA-1 content hash.
 	 *
 	 * @param string $hash A sha1 hash to look for
-	 * @return array
+	 * @return File[]
 	 */
 	function findBySha1( $hash ) {
 		$dbr = $this->getSlaveDB();

includes/filerepo/RepoGroup.php

@@ -221,7 +221,7 @@ class RepoGroup {
 	/**
 	 * Interface for FileRepo::checkRedirect()
 	 * @param Title $title
-	 * @return bool
+	 * @return bool|Title
 	 */
 	function checkRedirect( Title $title ) {
 		if ( !$this->reposInitialised ) {
@@ -273,7 +273,7 @@ class RepoGroup {
 	 * Find all instances of files with this key
 	 *
 	 * @param string $hash Base 36 SHA-1 hash
-	 * @return array Array of File objects
+	 * @return File[]
 	 */
 	function findBySha1( $hash ) {
 		if ( !$this->reposInitialised ) {

includes/specials/SpecialActiveusers.php

@@ -46,6 +46,11 @@ class ActiveUsersPager extends UsersPager {
 	 */
 	protected $hideRights = array();
 
+	/**
+	 * @var array
+	 */
+	private $blockStatusByUid;
+
 	/**
 	 * @param IContextSource $context
 	 * @param null $group Unused

includes/upload/UploadBase.php

@@ -171,6 +171,7 @@ abstract class UploadBase {
 			return null;
 		}
 
+		/** @var UploadBase $handler */
 		$handler = new $className;
 
 		$handler->initializeFromRequest( $request );
@@ -882,7 +883,7 @@ abstract class UploadBase {
 	/**
 	 * Return the local file and initializes if necessary.
 	 *
-	 * @return LocalFile|null
+	 * @return LocalFile|UploadStashFile|null
 	 */
 	public function getLocalFile() {
 		if ( is_null( $this->mLocalFile ) ) {
@@ -1884,7 +1885,7 @@ abstract class UploadBase {
 	 * Get the current status of a chunked upload (used for polling).
 	 * The status will be read from the *current* user session.
 	 * @param string $statusKey
-	 * @return array|bool
+	 * @return Status[]|bool
 	 */
 	public static function getSessionStatus( $statusKey ) {
 		return isset( $_SESSION[self::SESSION_STATUS_KEY][$statusKey] )

includes/upload/UploadFromChunks.php

@@ -32,6 +32,8 @@ class UploadFromChunks extends UploadFromFile {
 	protected $mChunkIndex;
 	protected $mFileKey;
 	protected $mVirtualTempPath;
+	/** @var LocalRepo */
+	private $repo;
 
 	/**
 	 * Setup local pointers to stash, repo and user (similar to UploadFromStash)