From 2b676156ba252dcb39aa90b65799defeb727cf1c Mon Sep 17 00:00:00 2001
From: Sam Reed <reedy@users.mediawiki.org>
Date: Sat, 28 May 2011 18:58:51 +0000
Subject: [PATCH] And even more documentation

---
 includes/Article.php                       |  2 +-
 includes/Autopromote.php                   |  4 ++--
 includes/BacklinkCache.php                 |  2 ++
 includes/Block.php                         |  5 ++++-
 includes/Cdb.php                           |  2 ++
 includes/ExternalStore.php                 | 11 ++++++++---
 includes/Fallback.php                      | 12 +++++++++---
 includes/actions/CreditsAction.php         |  4 ++--
 includes/api/ApiBase.php                   |  2 +-
 includes/api/ApiQueryStashImageInfo.php    |  2 +-
 includes/api/ApiQueryUserContributions.php |  2 ++
 includes/api/ApiUpload.php                 |  2 +-
 includes/cache/HTMLCacheUpdate.php         |  2 ++
 includes/cache/LinkBatch.php               |  5 +++--
 includes/cache/LinkCache.php               | 10 ++++++++++
 includes/conf/DatabaseConf.php             |  5 +++++
 includes/db/DatabaseSqlite.php             | 12 ++++++++++++
 includes/db/LBFactory.php                  |  4 ++++
 includes/db/LBFactory_Multi.php            |  2 +-
 includes/db/LBFactory_Single.php           |  4 ++++
 includes/db/LoadBalancer.php               |  4 ++++
 includes/db/LoadMonitor.php                |  5 +++++
 includes/filerepo/FileRepo.php             |  8 +++++++-
 includes/filerepo/ForeignAPIRepo.php       | 14 +++++++++++---
 24 files changed, 103 insertions(+), 22 deletions(-)

diff --git a/includes/Article.php b/includes/Article.php
index a5110f47bd..a7468e921a 100644
--- a/includes/Article.php
+++ b/includes/Article.php
@@ -76,7 +76,7 @@ class Article {
 
 	/**
 	 * Constructor and clear the article
-	 * @param $title Reference to a Title object.
+	 * @param $title Title Reference to a Title object.
 	 * @param $oldId Integer revision ID, null to fetch from request, zero for current
 	 */
 	public function __construct( Title $title, $oldId = null ) {
diff --git a/includes/Autopromote.php b/includes/Autopromote.php
index 97043da2ab..e630db95b2 100644
--- a/includes/Autopromote.php
+++ b/includes/Autopromote.php
@@ -40,7 +40,7 @@ class Autopromote {
 	 * self::checkCondition for evaluation of the latter type.
 	 *
 	 * @param $cond Mixed: a condition, possibly containing other conditions
-	 * @param $user The user to check the conditions against
+	 * @param $user User The user to check the conditions against
 	 * @return bool Whether the condition is true
 	 */
 	private static function recCheckCondition( $cond, User $user ) {
@@ -101,7 +101,7 @@ class Autopromote {
 	 * ates them.
 	 *
 	 * @param $cond Array: A condition, which must not contain other conditions
-	 * @param $user The user to check the condition against
+	 * @param $user User The user to check the condition against
 	 * @return bool Whether the condition is true for the user
 	 */
 	private static function checkCondition( $cond, User $user ) {
diff --git a/includes/BacklinkCache.php b/includes/BacklinkCache.php
index 4677ef1c87..7de7faed0c 100644
--- a/includes/BacklinkCache.php
+++ b/includes/BacklinkCache.php
@@ -91,6 +91,8 @@ class BacklinkCache {
 
 	/**
 	 * Set the Database object to use
+	 *
+	 * @param $db DatabaseBase
 	 */
 	public function setDB( $db ) {
 		$this->db = $db;
diff --git a/includes/Block.php b/includes/Block.php
index d336dcc859..3bcab5467a 100644
--- a/includes/Block.php
+++ b/includes/Block.php
@@ -122,7 +122,10 @@ class Block {
 	/**
 	 * Check if two blocks are effectively equal.  Doesn't check irrelevant things like
 	 * the blocking user or the block timestamp, only things which affect the blocked user	 *
-	 * @return Boolean
+	 *
+	 * @param $block Block
+	 *
+	 * @return bool
 	 */
 	public function equals( Block $block ) {
 		return (
diff --git a/includes/Cdb.php b/includes/Cdb.php
index 8f93560bed..d7a2bca57a 100644
--- a/includes/Cdb.php
+++ b/includes/Cdb.php
@@ -55,6 +55,8 @@ abstract class CdbReader {
 
 	/**
 	 * Get a value with a given key. Only string values are supported.
+	 *
+	 * @param $key string
 	 */
 	abstract public function get( $key );
 }
diff --git a/includes/ExternalStore.php b/includes/ExternalStore.php
index 2f6b222cb8..d1cf4a57a8 100644
--- a/includes/ExternalStore.php
+++ b/includes/ExternalStore.php
@@ -78,7 +78,7 @@ class ExternalStore {
 	 * Store a data item to an external store, identified by a partial URL
 	 * The protocol part is used to identify the class, the rest is passed to the
 	 * class itself as a parameter.
-	 * @return The URL of the stored data item, or false on error
+	 * @return string The URL of the stored data item, or false on error
 	 */
 	static function insert( $url, $data, $params = array() ) {
 		list( $proto, $params ) = explode( '://', $url, 2 );
@@ -97,7 +97,7 @@ class ExternalStore {
 	 *
 	 * @param $data String
 	 * @param $storageParams Array: associative array of parameters for the ExternalStore object.
-	 * @return The URL of the stored data item, or false on error
+	 * @return string The URL of the stored data item, or false on error
 	 */
 	public static function insertToDefault( $data, $storageParams = array() ) {
 		global $wgDefaultExternalStore;
@@ -136,7 +136,12 @@ class ExternalStore {
 		}
 	}
 	
-	/** Like insertToDefault, but inserts on another wiki */
+	/**
+	 * @param $data
+	 * @param $wiki
+	 *
+	 * @return string
+	 */
 	public static function insertToForeignDefault( $data, $wiki ) {
 		return self::insertToDefault( $data, array( 'wiki' => $wiki ) );
 	}
diff --git a/includes/Fallback.php b/includes/Fallback.php
index 81ca6ad19c..2cca1e8184 100644
--- a/includes/Fallback.php
+++ b/includes/Fallback.php
@@ -37,8 +37,8 @@ class Fallback {
 			return utf8_encode( $string );
 		}
 		return $string;
-	}	
-	
+	}
+
 	/**
 	 * Fallback implementation for mb_substr, hardcoded to UTF-8.
 	 * Attempts to be at least _moderately_ efficient; best optimized
@@ -48,8 +48,14 @@ class Fallback {
 	 * Larger offsets are still fairly efficient for Latin text, but
 	 * can be up to 100x slower than native if the text is heavily
 	 * multibyte and we have to slog through a few hundred kb.
+	 * 
+	 * @param $str
+	 * @param $start
+	 * @param $count string
+	 *
+	 * @return string
 	 */
-	public static function mb_substr( $str, $start, $count='end' ) {
+	public static function mb_substr( $str, $start, $count = 'end' ) {
 		if( $start != 0 ) {
 			$split = self::mb_substr_split_unicode( $str, intval( $start ) );
 			$str = substr( $str, $split );
diff --git a/includes/actions/CreditsAction.php b/includes/actions/CreditsAction.php
index 9ce7963eb3..25434abbf3 100644
--- a/includes/actions/CreditsAction.php
+++ b/includes/actions/CreditsAction.php
@@ -51,8 +51,8 @@ class CreditsAction extends FormlessAction {
 	}
 
 	/**
-	 * Get a list of contributors of $article
-	 * @param $article Article object
+	 * Get a list of contributors
+	 *
 	 * @param $cnt Int: maximum list of contributors to show
 	 * @param $showIfMax Bool: whether to contributors if there more than $cnt
 	 * @return String: html
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index a2c8769c86..cff19588ec 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -123,7 +123,7 @@ abstract class ApiBase {
 	/**
 	 * Get the name of the module as shown in the profiler log
 	 *
-	 * @param $db
+	 * @param $db DatabaseBase
 	 *
 	 * @return string
 	 */
diff --git a/includes/api/ApiQueryStashImageInfo.php b/includes/api/ApiQueryStashImageInfo.php
index 437a13e5b3..e8dea83487 100644
--- a/includes/api/ApiQueryStashImageInfo.php
+++ b/includes/api/ApiQueryStashImageInfo.php
@@ -95,7 +95,7 @@ class ApiQueryStashImageInfo extends ApiQueryImageInfo {
 
 	/**
 	 * Return the API documentation for the parameters.
-	 * @return {Array} parameter documentation.
+	 * @return Array parameter documentation.
 	 */
 	public function getParamDescription() {
 		$p = $this->getModulePrefix();
diff --git a/includes/api/ApiQueryUserContributions.php b/includes/api/ApiQueryUserContributions.php
index 9e68b0f360..b294589543 100644
--- a/includes/api/ApiQueryUserContributions.php
+++ b/includes/api/ApiQueryUserContributions.php
@@ -121,6 +121,8 @@ class ApiQueryContributions extends ApiQueryBase {
 	/**
 	 * Validate the 'user' parameter and set the value to compare
 	 * against `revision`.`rev_user_text`
+	 *
+	 * @param $user string
 	 */
 	private function prepareUsername( $user ) {
 		if ( !is_null( $user ) && $user !== '' ) {
diff --git a/includes/api/ApiUpload.php b/includes/api/ApiUpload.php
index 5c39e2149e..c123bac42a 100644
--- a/includes/api/ApiUpload.php
+++ b/includes/api/ApiUpload.php
@@ -136,7 +136,7 @@ class ApiUpload extends ApiBase {
 	 * Stash the file and return the session key
 	 * Also re-raises exceptions with slightly more informative message strings (useful for API)
 	 * @throws MWException
-	 * @return {String} session key
+	 * @return String session key
 	 */
 	function performStash() {
 		try {
diff --git a/includes/cache/HTMLCacheUpdate.php b/includes/cache/HTMLCacheUpdate.php
index d923bc0190..d542800db2 100644
--- a/includes/cache/HTMLCacheUpdate.php
+++ b/includes/cache/HTMLCacheUpdate.php
@@ -90,6 +90,8 @@ class HTMLCacheUpdate
 	 * Partition the current range given by $this->mStart and $this->mEnd,
 	 * using a pre-calculated title array which gives the links in that range.
 	 * Queue the resulting jobs.
+	 *
+	 * @param $titleArray array
 	 */
 	protected function insertJobsFromTitles( $titleArray ) {
 		# We make subpartitions in the sense that the start of the first job
diff --git a/includes/cache/LinkBatch.php b/includes/cache/LinkBatch.php
index 9486815c95..e6f101dd8a 100644
--- a/includes/cache/LinkBatch.php
+++ b/includes/cache/LinkBatch.php
@@ -27,14 +27,15 @@ class LinkBatch {
 	 * Use ->setCaller( __METHOD__ ) to indicate which code is using this
 	 * class. Only used in debugging output.
 	 * @since 1.17
+	 *
+	 * @param $caller
 	 */
 	public function setCaller( $caller ) {
 		$this->caller = $caller;
 	}
 
 	/**
-	 * @param  $title Title
-	 * @return void
+	 * @param $title Title
 	 */
 	public function addObj( $title ) {
 		if ( is_object( $title ) ) {
diff --git a/includes/cache/LinkCache.php b/includes/cache/LinkCache.php
index 6ffb7e0112..aeb10eb012 100644
--- a/includes/cache/LinkCache.php
+++ b/includes/cache/LinkCache.php
@@ -34,11 +34,17 @@ class LinkCache {
 
 	/**
 	 * General accessor to get/set whether SELECT FOR UPDATE should be used
+	 *
+	 * @return bool
 	 */
 	public function forUpdate( $update = null ) {
 		return wfSetVar( $this->mForUpdate, $update );
 	}
 
+	/**
+	 * @param $title
+	 * @return array|int
+	 */
 	public function getGoodLinkID( $title ) {
 		if ( array_key_exists( $title, $this->mGoodLinks ) ) {
 			return $this->mGoodLinks[$title];
@@ -63,6 +69,10 @@ class LinkCache {
 		}
 	}
 
+	/**
+	 * @param $title
+	 * @return bool
+	 */
 	public function isBadLink( $title ) {
 		return array_key_exists( $title, $this->mBadLinks );
 	}
diff --git a/includes/conf/DatabaseConf.php b/includes/conf/DatabaseConf.php
index dee41ee6d8..e2e36cef2c 100644
--- a/includes/conf/DatabaseConf.php
+++ b/includes/conf/DatabaseConf.php
@@ -36,6 +36,11 @@ class DatabaseConf extends Conf {
 
 	/**
 	 * @see Conf::writeSetting()
+	 *
+	 * @param $name
+	 * @param $value
+	 * 
+	 * @return bool
 	 */
 	protected function writeSetting( $name, $value ) {
 		$dbw = wfGetDB( DB_MASTER );
diff --git a/includes/db/DatabaseSqlite.php b/includes/db/DatabaseSqlite.php
index 123eaa3659..4faa4eb1e6 100644
--- a/includes/db/DatabaseSqlite.php
+++ b/includes/db/DatabaseSqlite.php
@@ -27,6 +27,11 @@ class DatabaseSqlite extends DatabaseBase {
 	/**
 	 * Constructor.
 	 * Parameters $server, $user and $password are not used.
+	 * @param $server string
+	 * @param $user string
+	 * @param $password string
+	 * @param $dbName string
+	 * @param $flags int
 	 */
 	function __construct( $server = false, $user = false, $password = false, $dbName = false, $flags = 0 ) {
 		$this->mName = $dbName;
@@ -58,6 +63,13 @@ class DatabaseSqlite extends DatabaseBase {
 
 	/** Open an SQLite database and return a resource handle to it
 	 *  NOTE: only $dbName is used, the other parameters are irrelevant for SQLite databases
+	 *
+	 * @param $server
+	 * @param $user
+	 * @param $pass
+	 * @param $dbName
+	 *
+	 * @return PDO
 	 */
 	function open( $server, $user, $pass, $dbName ) {
 		global $wgSQLiteDataDir;
diff --git a/includes/db/LBFactory.php b/includes/db/LBFactory.php
index f0973190b1..22a849609c 100644
--- a/includes/db/LBFactory.php
+++ b/includes/db/LBFactory.php
@@ -91,6 +91,8 @@ abstract class LBFactory {
 	 *
 	 * @param $cluster String: external storage cluster, or false for core
 	 * @param $wiki String: wiki ID, or false for the current wiki
+	 *
+	 * @return LoadBalancer
 	 */
 	abstract function newExternalLB( $cluster, $wiki = false );
 
@@ -99,6 +101,8 @@ abstract class LBFactory {
 	 *
 	 * @param $cluster String: external storage cluster, or false for core
 	 * @param $wiki String: wiki ID, or false for the current wiki
+	 *
+	 * @return LoadBalancer
 	 */
 	abstract function &getExternalLB( $cluster, $wiki = false );
 
diff --git a/includes/db/LBFactory_Multi.php b/includes/db/LBFactory_Multi.php
index eb6226a832..61e56e7872 100644
--- a/includes/db/LBFactory_Multi.php
+++ b/includes/db/LBFactory_Multi.php
@@ -99,7 +99,7 @@ class LBFactory_Multi extends LBFactory {
 	}
 
 	/**
-	 * @param $wiki
+	 * @param $wiki string
 	 * @return LoadBalancer
 	 */
 	function newMainLB( $wiki = false ) {
diff --git a/includes/db/LBFactory_Single.php b/includes/db/LBFactory_Single.php
index cf5ea7cf6f..5ccaa15ffa 100644
--- a/includes/db/LBFactory_Single.php
+++ b/includes/db/LBFactory_Single.php
@@ -85,6 +85,10 @@ class LoadBalancer_Single extends LoadBalancer {
 	}
 
 	/**
+	 *
+	 * @param $server
+	 * @param $dbNameOverride
+	 *
 	 * @return DatabaseBase
 	 */
 	function reallyOpenConnection( $server, $dbNameOverride = false ) {
diff --git a/includes/db/LoadBalancer.php b/includes/db/LoadBalancer.php
index bfbc9d8c26..5cc9c1b622 100644
--- a/includes/db/LoadBalancer.php
+++ b/includes/db/LoadBalancer.php
@@ -948,6 +948,10 @@ class LoadBalancer {
 	/**
 	 * Get lag time for each server
 	 * Results are cached for a short time in memcached, and indefinitely in the process cache
+	 *
+	 * @param $wiki
+	 * 
+	 * @return array
 	 */
 	function getLagTimes( $wiki = false ) {
 		# Try process cache
diff --git a/includes/db/LoadMonitor.php b/includes/db/LoadMonitor.php
index f8bf3af1d3..4bfbe9436a 100644
--- a/includes/db/LoadMonitor.php
+++ b/includes/db/LoadMonitor.php
@@ -47,6 +47,11 @@ interface LoadMonitor {
 
 	/**
 	 * Return an estimate of replication lag for each server
+	 *
+	 * @param $serverIndexes
+	 * @param $wiki
+	 * 
+	 * @return array
 	 */
 	function getLagTimes( $serverIndexes, $wiki );
 }
diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php
index 6b87f63034..ad4eb96e06 100644
--- a/includes/filerepo/FileRepo.php
+++ b/includes/filerepo/FileRepo.php
@@ -52,6 +52,10 @@ abstract class FileRepo {
 
 	/**
 	 * Determine if a string is an mwrepo:// URL
+	 *
+	 * @param $url string
+	 *
+	 * @return bool
 	 */
 	static function isVirtualUrl( $url ) {
 		return substr( $url, 0, 9 ) == 'mwrepo://';
@@ -93,7 +97,7 @@ abstract class FileRepo {
 	 * version control should return false if the time is specified.
 	 *
 	 * @param $title Mixed: Title object or string
-	 * @param $options Associative array of options:
+	 * @param $options array Associative array of options:
 	 *     time:           requested time for an archived image, or false for the
 	 *                     current version. An image object will be returned which was
 	 *                     created at the specified time.
@@ -103,6 +107,8 @@ abstract 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|false
 	 */
 	function findFile( $title, $options = array() ) {
 		$time = isset( $options['time'] ) ? $options['time'] : false;
diff --git a/includes/filerepo/ForeignAPIRepo.php b/includes/filerepo/ForeignAPIRepo.php
index 44449b30cf..38b6f5e707 100644
--- a/includes/filerepo/ForeignAPIRepo.php
+++ b/includes/filerepo/ForeignAPIRepo.php
@@ -75,6 +75,8 @@ class ForeignAPIRepo extends FileRepo {
 	/**
 	 * Per docs in FileRepo, this needs to return false if we don't support versioned
 	 * files. Well, we don't.
+	 *
+	 * @return File
 	 */
 	function newFile( $title, $time = false ) {
 		if ( $time ) {
@@ -83,24 +85,30 @@ class ForeignAPIRepo extends FileRepo {
 		return parent::newFile( $title, $time );
 	}
 
-/**
- * No-ops
- */
+	/**
+	 * No-ops
+	 */
+
 	function storeBatch( $triplets, $flags = 0 ) {
 		return false;
 	}
+
 	function storeTemp( $originalName, $srcPath ) {
 		return false;
 	}
+
 	function append( $srcPath, $toAppendPath, $flags = 0 ){
 		return false;
 	}
+
 	function appendFinish( $toAppendPath ){
 		return false;
 	}
+
 	function publishBatch( $triplets, $flags = 0 ) {
 		return false;
 	}
+
 	function deleteBatch( $sourceDestPairs ) {
 		return false;
 	}
-- 
2.20.1