Flesh out parameter documentation etc
authorReedy <reedy@wikimedia.org>
Wed, 20 Jun 2012 21:45:21 +0000 (22:45 +0100)
committerGerrit Code Review <gerrit@wikimedia.org>
Mon, 9 Jul 2012 12:44:13 +0000 (12:44 +0000)
Remove some trailing whitespace

A bit of code simplification

Change-Id: Iea96a2482c53868713a43569be4e5de4c9edb2a2

13 files changed:
includes/objectcache/APCBagOStuff.php
includes/objectcache/BagOStuff.php
includes/objectcache/DBABagOStuff.php
includes/objectcache/EhcacheBagOStuff.php
includes/objectcache/EmptyBagOStuff.php
includes/objectcache/HashBagOStuff.php
includes/objectcache/MemcachedBagOStuff.php
includes/objectcache/MemcachedPeclBagOStuff.php
includes/objectcache/MemcachedPhpBagOStuff.php
includes/objectcache/MultiWriteBagOStuff.php
includes/objectcache/ObjectCache.php
includes/objectcache/SqlBagOStuff.php
includes/objectcache/WinCacheBagOStuff.php

index b9a6a69..5a7729b 100644 (file)
  * @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'];
index e6ba042..0aebfa3 100644 (file)
@@ -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 ) ) {
index 63ad4de..8483d7e 100644 (file)
@@ -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 );
index fb31d5c..f86cf15 100644 (file)
@@ -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 ) );
index abc6bcf..bd28b24 100644 (file)
  * @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;
        }
index 26b949f..799f26a 100644 (file)
@@ -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 );
        }
index 1312866..324b3a6 100644 (file)
@@ -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] );
        }
index 65d736a..76886eb 100644 (file)
@@ -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 ) {
index c562134..a46dc71 100644 (file)
@@ -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 );
index fd60e72..e496ddd 100644 (file)
@@ -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 ) {
index 2e00e16..9b360f3 100644 (file)
@@ -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 ) {
index 209975b..5ad7020 100644 (file)
@@ -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 ) {
index 4fd3cf4..21aa39e 100644 (file)
@@ -74,6 +74,9 @@ class WinCacheBagOStuff extends BagOStuff {
                return true;
        }
 
+       /**
+        * @return Array
+        */
        public function keys() {
                $info = wincache_ucache_info();
                $list = $info['ucache_entries'];