Flesh out parameter documentation etc

Remove some trailing whitespace

A bit of code simplification

Change-Id: Iea96a2482c53868713a43569be4e5de4c9edb2a2

includes/objectcache/APCBagOStuff.php

@@ -27,6 +27,11 @@
  * @ingroup Cache
  */
 class APCBagOStuff extends BagOStuff {
+
+	/**
+	 * @param $key string
+	 * @return mixed
+	 */
 	public function get( $key ) {
 		$val = apc_fetch( $key );
 
@@ -37,18 +42,32 @@ class APCBagOStuff extends BagOStuff {
 		return $val;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	public function set( $key, $value, $exptime = 0 ) {
 		apc_store( $key, serialize( $value ), $exptime );
 
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	public function delete( $key, $time = 0 ) {
 		apc_delete( $key );
 
 		return true;
 	}
 
+	/**
+	 * @return Array
+	 */
 	public function keys() {
 		$info = apc_cache_info( 'user' );
 		$list = $info['cache_list'];

includes/objectcache/BagOStuff.php

@@ -153,6 +153,7 @@ abstract class BagOStuff {
 	/**
 	 * @param $key string
 	 * @param $value mixed
+	 * @param $exptime int
 	 * @return bool success
 	 */
 	public function replace( $key, $value, $exptime = 0 ) {
@@ -166,7 +167,7 @@ abstract class BagOStuff {
 	 * @param $key String: Key to increase
 	 * @param $value Integer: Value to add to $key (Default 1)
 	 * @return null if lock is not possible else $key value increased by $value
-	 * @return success
+	 * @return bool success
 	 */
 	public function incr( $key, $value = 1 ) {
 		if ( !$this->lock( $key ) ) {

includes/objectcache/DBABagOStuff.php

@@ -35,6 +35,9 @@
 class DBABagOStuff extends BagOStuff {
 	var $mHandler, $mFile, $mReader, $mWriter, $mDisabled;
 
+	/**
+	 * @param $params array
+	 */
 	public function __construct( $params ) {
 		global $wgDBAhandler;
 
@@ -63,6 +66,7 @@ class DBABagOStuff extends BagOStuff {
 	}
 
 	/**
+	 * @param $blob string
 	 * @return array list containing value first and expiry second
 	 */
 	function decode( $blob ) {
@@ -76,6 +80,9 @@ class DBABagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @return resource
+	 */
 	function getReader() {
 		if ( file_exists( $this->mFile ) ) {
 			$handle = dba_open( $this->mFile, 'rl', $this->mHandler );
@@ -90,6 +97,9 @@ class DBABagOStuff extends BagOStuff {
 		return $handle;
 	}
 
+	/**
+	 * @return resource
+	 */
 	function getWriter() {
 		$handle = dba_open( $this->mFile, 'cl', $this->mHandler );
 
@@ -100,6 +110,10 @@ class DBABagOStuff extends BagOStuff {
 		return $handle;
 	}
 
+	/**
+	 * @param $key string
+	 * @return mixed|null|string
+	 */
 	function get( $key ) {
 		wfProfileIn( __METHOD__ );
 		wfDebug( __METHOD__ . "($key)\n" );
@@ -129,6 +143,12 @@ class DBABagOStuff extends BagOStuff {
 		return $val;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	function set( $key, $value, $exptime = 0 ) {
 		wfProfileIn( __METHOD__ );
 		wfDebug( __METHOD__ . "($key)\n" );
@@ -148,6 +168,11 @@ class DBABagOStuff extends BagOStuff {
 		return $ret;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	function delete( $key, $time = 0 ) {
 		wfProfileIn( __METHOD__ );
 		wfDebug( __METHOD__ . "($key)\n" );
@@ -165,6 +190,12 @@ class DBABagOStuff extends BagOStuff {
 		return $ret;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	function add( $key, $value, $exptime = 0 ) {
 		wfProfileIn( __METHOD__ );
 
@@ -197,6 +228,9 @@ class DBABagOStuff extends BagOStuff {
 		return $ret;
 	}
 
+	/**
+	 * @return Array
+	 */
 	function keys() {
 		$reader = $this->getReader();
 		$k1 = dba_firstkey( $reader );

includes/objectcache/EhcacheBagOStuff.php

@@ -33,6 +33,9 @@ class EhcacheBagOStuff extends BagOStuff {
 	
 	var $curls = array();
 
+	/**
+	 * @param $params array
+	 */
 	function __construct( $params ) {
 		if ( !defined( 'CURLOPT_TIMEOUT_MS' ) ) {
 			throw new MWException( __CLASS__.' requires curl version 7.16.2 or later.' );
@@ -59,6 +62,10 @@ class EhcacheBagOStuff extends BagOStuff {
 		);
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool|mixed
+	 */
 	public function get( $key ) {
 		wfProfileIn( __METHOD__ );
 		$response = $this->doItemRequest( $key );
@@ -93,6 +100,12 @@ class EhcacheBagOStuff extends BagOStuff {
 		return $data;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $expiry int
+	 * @return bool
+	 */
 	public function set( $key, $value, $expiry = 0 ) {
 		wfProfileIn( __METHOD__ );
 		$expiry = $this->convertExpiry( $expiry );
@@ -130,6 +143,11 @@ class EhcacheBagOStuff extends BagOStuff {
 		return $result;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	public function delete( $key, $time = 0 ) {
 		wfProfileIn( __METHOD__ );
 		$response = $this->doItemRequest( $key,
@@ -145,6 +163,10 @@ class EhcacheBagOStuff extends BagOStuff {
 		return $result;
 	}
 
+	/**
+	 * @param $key string
+	 * @return string
+	 */
 	protected function getCacheUrl( $key ) {
 		if ( count( $this->servers ) == 1 ) {
 			$server = reset( $this->servers );
@@ -172,6 +194,13 @@ class EhcacheBagOStuff extends BagOStuff {
 		return $this->curls[$cacheUrl];
 	}
 
+	/**
+	 * @param $key string
+	 * @param $data
+	 * @param $type
+	 * @param $ttl
+	 * @return int
+	 */
 	protected function attemptPut( $key, $data, $type, $ttl ) {
 		// In initial benchmarking, it was 30 times faster to use CURLOPT_POST 
 		// than CURLOPT_UPLOAD with CURLOPT_READFUNCTION. This was because
@@ -196,6 +225,10 @@ class EhcacheBagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool
+	 */
 	protected function createCache( $key ) {
 		wfDebug( __METHOD__.": creating cache for $key\n" );
 		$response = $this->doCacheRequest( $key, 
@@ -208,21 +241,26 @@ class EhcacheBagOStuff extends BagOStuff {
 			wfDebug( __CLASS__.": failed to create cache for $key\n" );
 			return false;
 		}
-		if ( $response['http_code'] == 201 /* created */ 
-			|| $response['http_code'] == 409 /* already there */ ) 
-		{
-			return true;
-		} else {
-			return false;
-		}			
+		return ( $response['http_code'] == 201 /* created */
+			|| $response['http_code'] == 409 /* already there */ );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $curlOptions array
+	 * @return array|bool|mixed
+	 */
 	protected function doCacheRequest( $key, $curlOptions = array() ) {
 		$cacheUrl = $this->getCacheUrl( $key );
 		$curl = $this->getCurl( $cacheUrl );
 		return $this->doRequest( $curl, $cacheUrl, $curlOptions );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $curlOptions array
+	 * @return array|bool|mixed
+	 */
 	protected function doItemRequest( $key, $curlOptions = array() ) {
 		$cacheUrl = $this->getCacheUrl( $key );
 		$curl = $this->getCurl( $cacheUrl );
@@ -230,6 +268,13 @@ class EhcacheBagOStuff extends BagOStuff {
 		return $this->doRequest( $curl, $url, $curlOptions );
 	}
 
+	/**
+	 * @param $curl
+	 * @param $url string
+	 * @param $curlOptions array
+	 * @return array|bool|mixed
+	 * @throws MWException
+	 */
 	protected function doRequest( $curl, $url, $curlOptions = array() ) {
 		if ( array_diff_key( $curlOptions, $this->curlOptions ) ) {
 			// var_dump( array_diff_key( $curlOptions, $this->curlOptions ) );

includes/objectcache/EmptyBagOStuff.php

@@ -27,14 +27,30 @@
  * @ingroup Cache
  */
 class EmptyBagOStuff extends BagOStuff {
+
+	/**
+	 * @param $key string
+	 * @return bool
+	 */
 	function get( $key ) {
 		return false;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exp int
+	 * @return bool
+	 */
 	function set( $key, $value, $exp = 0 ) {
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	function delete( $key, $time = 0 ) {
 		return true;
 	}

includes/objectcache/HashBagOStuff.php

@@ -34,6 +34,10 @@ class HashBagOStuff extends BagOStuff {
 		$this->bag = array();
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool
+	 */
 	protected function expire( $key ) {
 		$et = $this->bag[$key][1];
 
@@ -46,6 +50,10 @@ class HashBagOStuff extends BagOStuff {
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool|mixed
+	 */
 	function get( $key ) {
 		if ( !isset( $this->bag[$key] ) ) {
 			return false;
@@ -58,10 +66,22 @@ class HashBagOStuff extends BagOStuff {
 		return $this->bag[$key][0];
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	function set( $key, $value, $exptime = 0 ) {
 		$this->bag[$key] = array( $value, $this->convertExpiry( $exptime ) );
+		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	function delete( $key, $time = 0 ) {
 		if ( !isset( $this->bag[$key] ) ) {
 			return false;
@@ -72,6 +92,9 @@ class HashBagOStuff extends BagOStuff {
 		return true;
 	}
 
+	/**
+	 * @return array
+	 */
 	function keys() {
 		return array_keys( $this->bag );
 	}

includes/objectcache/MemcachedBagOStuff.php

@@ -119,6 +119,7 @@ class MemcachedBagOStuff extends BagOStuff {
 	 * the other control characters for compatibility with libmemcached
 	 * verify_key. We leave other punctuation alone, to maximise backwards
 	 * compatibility.
+	 * @param $key string
 	 * @return string
 	 */
 	public function encodeKey( $key ) {
@@ -126,6 +127,10 @@ class MemcachedBagOStuff extends BagOStuff {
 			array( $this, 'encodeKeyCallback' ), $key );
 	}
 
+	/**
+	 * @param $m array
+	 * @return string
+	 */
 	protected function encodeKeyCallback( $m ) {
 		return rawurlencode( $m[0] );
 	}

includes/objectcache/MemcachedPeclBagOStuff.php

@@ -141,6 +141,7 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
 	/**
 	 * @param $key string
 	 * @param $value int
+	 * @param $exptime int
 	 * @return Mixed
 	 */
 	public function add( $key, $value, $exptime = 0 ) {
@@ -188,8 +189,9 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
 	 * the client, but some day we might find a case where it should be
 	 * different.
 	 *
-	 * @param $key The key used by the caller, or false if there wasn't one.
-	 * @param $result The return value
+	 * @param $key string The key used by the caller, or false if there wasn't one.
+	 * @param $result Mixed The return value
+	 * @return Mixed
 	 */
 	protected function checkResult( $key, $result ) {
 		if ( $result !== false ) {

includes/objectcache/MemcachedPhpBagOStuff.php

@@ -68,7 +68,7 @@ class MemcachedPhpBagOStuff extends MemcachedBagOStuff {
 	/**
 	 * @param $key
 	 * @param $timeout int
-	 * @return
+	 * @return bool
 	 */
 	public function lock( $key, $timeout = 0 ) {
 		return $this->client->lock( $this->encodeKey( $key ), $timeout );

includes/objectcache/MultiWriteBagOStuff.php

@@ -34,11 +34,12 @@ class MultiWriteBagOStuff extends BagOStuff {
 	/**
 	 * Constructor. Parameters are:
 	 *
-	 *   - caches:   This should have a numbered array of cache parameter 
+	 *   - caches:   This should have a numbered array of cache parameter
 	 *               structures, in the style required by $wgObjectCaches. See
 	 *               the documentation of $wgObjectCaches for more detail.
 	 *
 	 * @param $params array
+	 * @throws MWException
 	 */
 	public function __construct( $params ) {
 		if ( !isset( $params['caches'] ) ) {
@@ -51,10 +52,17 @@ class MultiWriteBagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @param $debug bool
+	 */
 	public function setDebug( $debug ) {
 		$this->doWrite( 'setDebug', $debug );
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool|mixed
+	 */
 	public function get( $key ) {
 		foreach ( $this->caches as $cache ) {
 			$value = $cache->get( $key );
@@ -65,30 +73,68 @@ class MultiWriteBagOStuff extends BagOStuff {
 		return false;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	public function set( $key, $value, $exptime = 0 ) {
 		return $this->doWrite( 'set', $key, $value, $exptime );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	public function delete( $key, $time = 0 ) {
 		return $this->doWrite( 'delete', $key, $time );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	public function add( $key, $value, $exptime = 0 ) {
 		return $this->doWrite( 'add', $key, $value, $exptime );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	public function replace( $key, $value, $exptime = 0 ) {
 		return $this->doWrite( 'replace', $key, $value, $exptime );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value int
+	 * @return bool|null
+	 */
 	public function incr( $key, $value = 1 ) {
 		return $this->doWrite( 'incr', $key, $value );
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value int
+	 * @return bool
+	 */
 	public function decr( $key, $value = 1 ) {
 		return $this->doWrite( 'decr', $key, $value );
-	}	
+	}
 
+	/**
+	 * @param $key string
+	 * @param $timeout int
+	 * @return bool
+	 */
 	public function lock( $key, $timeout = 0 ) {
 		// Lock only the first cache, to avoid deadlocks
 		if ( isset( $this->caches[0] ) ) {
@@ -98,6 +144,10 @@ class MultiWriteBagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool
+	 */
 	public function unlock( $key ) {
 		if ( isset( $this->caches[0] ) ) {
 			return $this->caches[0]->unlock( $key );
@@ -106,6 +156,10 @@ class MultiWriteBagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @param $method string
+	 * @return bool
+	 */
 	protected function doWrite( $method /*, ... */ ) {
 		$ret = true;
 		$args = func_get_args();
@@ -120,9 +174,11 @@ class MultiWriteBagOStuff extends BagOStuff {
 	}
 
 	/**
-	 * Delete objects expiring before a certain date. 
+	 * Delete objects expiring before a certain date.
 	 *
 	 * Succeed if any of the child caches succeed.
+	 * @param $date string
+	 * @param $progressCallback bool|callback
 	 * @return bool
 	 */
 	public function deleteObjectsExpiringBefore( $date, $progressCallback = false ) {

includes/objectcache/ObjectCache.php

@@ -32,9 +32,9 @@ class ObjectCache {
 	/**
 	 * Get a cached instance of the specified type of cache object.
 	 *
-	 * @param $id
+	 * @param $id string
 	 *
-	 * @return object
+	 * @return ObjectCache
 	 */
 	static function getInstance( $id ) {
 		if ( isset( self::$instances[$id] ) ) {
@@ -56,8 +56,9 @@ class ObjectCache {
 	/**
 	 * Create a new cache object of the specified type.
 	 *
-	 * @param $id
+	 * @param $id string
 	 *
+	 * @throws MWException
 	 * @return ObjectCache
 	 */
 	static function newFromId( $id ) {
@@ -76,6 +77,7 @@ class ObjectCache {
 	 *
 	 * @param $params array
 	 *
+	 * @throws MWException
 	 * @return ObjectCache
 	 */
 	static function newFromParams( $params ) {
@@ -99,6 +101,8 @@ class ObjectCache {
 	 * be an alias to the configured cache choice for that.
 	 * If no cache choice is configured (by default $wgMainCacheType is CACHE_NONE),
 	 * then CACHE_ANYTHING will forward to CACHE_DB.
+	 * @param $params array
+	 * @return ObjectCache
 	 */
 	static function newAnything( $params ) {
 		global $wgMainCacheType, $wgMessageCacheType, $wgParserCacheType;
@@ -114,6 +118,8 @@ class ObjectCache {
 	/**
 	 * Factory function referenced from DefaultSettings.php for CACHE_ACCEL.
 	 *
+	 * @param $params array
+	 * @throws MWException
 	 * @return ObjectCache
 	 */
 	static function newAccelerator( $params ) {

includes/objectcache/SqlBagOStuff.php

@@ -122,6 +122,7 @@ class SqlBagOStuff extends BagOStuff {
 
 	/**
 	 * Get the table name for a given key
+	 * @param $key string
 	 * @return string
 	 */
 	protected function getTableByKey( $key ) {
@@ -135,6 +136,7 @@ class SqlBagOStuff extends BagOStuff {
 
 	/**
 	 * Get the table name for a given shard index
+	 * @param $index int
 	 * @return string
 	 */
 	protected function getTableByShard( $index ) {
@@ -147,11 +149,19 @@ class SqlBagOStuff extends BagOStuff {
 		}
 	}
 
+	/**
+	 * @param $key string
+	 * @return mixed
+	 */
 	public function get( $key ) {
 		$values = $this->getMulti( array( $key ) );
 		return $values[$key];
 	}
 
+	/**
+	 * @param $keys array
+	 * @return Array
+	 */
 	public function getMulti( array $keys ) {
 		$values = array(); // array of (key => value)
 
@@ -208,6 +218,12 @@ class SqlBagOStuff extends BagOStuff {
 		return $values;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime int
+	 * @return bool
+	 */
 	public function set( $key, $value, $exptime = 0 ) {
 		$db = $this->getDB();
 		$exptime = intval( $exptime );
@@ -247,6 +263,11 @@ class SqlBagOStuff extends BagOStuff {
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $time int
+	 * @return bool
+	 */
 	public function delete( $key, $time = 0 ) {
 		$db = $this->getDB();
 
@@ -266,6 +287,11 @@ class SqlBagOStuff extends BagOStuff {
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $step int
+	 * @return int|null
+	 */
 	public function incr( $key, $step = 1 ) {
 		$db = $this->getDB();
 		$tableName = $this->getTableByKey( $key );
@@ -316,6 +342,9 @@ class SqlBagOStuff extends BagOStuff {
 		return $newValue;
 	}
 
+	/**
+	 * @return Array
+	 */
 	public function keys() {
 		$db = $this->getDB();
 		$result = array();
@@ -331,10 +360,17 @@ class SqlBagOStuff extends BagOStuff {
 		return $result;
 	}
 
+	/**
+	 * @param $exptime string
+	 * @return bool
+	 */
 	protected function isExpired( $exptime ) {
 		return $exptime != $this->getMaxDateTime() && wfTimestamp( TS_UNIX, $exptime ) < time();
 	}
 
+	/**
+	 * @return string
+	 */
 	protected function getMaxDateTime() {
 		if ( time() > 0x7fffffff ) {
 			return $this->getDB()->timestamp( 1 << 62 );
@@ -366,6 +402,8 @@ class SqlBagOStuff extends BagOStuff {
 
 	/**
 	 * Delete objects from the database which expire before a certain date.
+	 * @param $timestamp string
+	 * @param $progressCallback bool|callback
 	 * @return bool
 	 */
 	public function deleteObjectsExpiringBefore( $timestamp, $progressCallback = false ) {

includes/objectcache/WinCacheBagOStuff.php

@@ -74,6 +74,9 @@ class WinCacheBagOStuff extends BagOStuff {
 		return true;
 	}
 
+	/**
+	 * @return Array
+	 */
 	public function keys() {
 		$info = wincache_ucache_info();
 		$list = $info['ucache_entries'];