From a7635530774e6dc50fa8b8d9ae261555fc8a51ba Mon Sep 17 00:00:00 2001
From: Aaron <aschulz@wikimedia.org>
Date: Thu, 26 Apr 2012 18:33:42 -0700
Subject: [PATCH] Improved BagOStuff documentation and made some return value
 tweaks.

Change-Id: I9d8f09c10ccc5e710bd8cae05b8f3da3c2d02056
---
 includes/objectcache/BagOStuff.php | 50 ++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 9 deletions(-)

diff --git a/includes/objectcache/BagOStuff.php b/includes/objectcache/BagOStuff.php
index 71469ab345..cdb66c49a3 100644
--- a/includes/objectcache/BagOStuff.php
+++ b/includes/objectcache/BagOStuff.php
@@ -56,8 +56,7 @@ abstract class BagOStuff {
 	/**
 	 * Get an item with the given key. Returns false if it does not exist.
 	 * @param $key string
-	 *
-	 * @return bool|Object
+	 * @return mixed Returns false on failure
 	 */
 	abstract public function get( $key );
 
@@ -65,7 +64,6 @@ abstract class BagOStuff {
 	 * Get an associative array containing the item for each of the given keys.
 	 * Each item will be false if it does not exist.
 	 * @param $keys Array List of strings
-	 *
 	 * @return Array
 	 */
 	public function getBatch( array $keys ) {
@@ -81,6 +79,7 @@ abstract class BagOStuff {
 	 * @param $key string
 	 * @param $value mixed
 	 * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
+	 * @return bool success
 	 */
 	abstract public function set( $key, $value, $exptime = 0 );
 
@@ -88,19 +87,33 @@ abstract class BagOStuff {
 	 * Delete an item.
 	 * @param $key string
 	 * @param $time int Amount of time to delay the operation (mostly memcached-specific)
+	 * @return bool success
 	 */
 	abstract public function delete( $key, $time = 0 );
 
+	/**
+	 * @param $key string
+	 * @param $timeout integer
+	 * @return bool success
+	 */
 	public function lock( $key, $timeout = 0 ) {
 		/* stub */
 		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @return bool success
+	 */
 	public function unlock( $key ) {
 		/* stub */
 		return true;
 	}
 
+	/**
+	 * @todo: what is this?
+	 * @return Array
+	 */
 	public function keys() {
 		/* stub */
 		return array();
@@ -122,24 +135,36 @@ abstract class BagOStuff {
 
 	/* *** Emulated functions *** */
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @param $exptime integer
+	 * @return bool success
+	 */
 	public function add( $key, $value, $exptime = 0 ) {
 		if ( !$this->get( $key ) ) {
-			$this->set( $key, $value, $exptime );
-
-			return true;
+			return $this->set( $key, $value, $exptime );
 		}
+		return true;
 	}
 
+	/**
+	 * @param $key string
+	 * @param $value mixed
+	 * @return bool success
+	 */
 	public function replace( $key, $value, $exptime = 0 ) {
 		if ( $this->get( $key ) !== false ) {
-			$this->set( $key, $value, $exptime );
+			return $this->set( $key, $value, $exptime );
 		}
+		return true;
 	}
 
 	/**
 	 * @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
 	 */
 	public function incr( $key, $value = 1 ) {
 		if ( !$this->lock( $key ) ) {
@@ -157,10 +182,18 @@ abstract class BagOStuff {
 		return $n;
 	}
 
+	/**
+	 * @param $key String
+	 * @param $value Integer
+	 * @return bool success
+	 */
 	public function decr( $key, $value = 1 ) {
 		return $this->incr( $key, - $value );
 	}
 
+	/**
+	 * @param $text string
+	 */
 	public function debug( $text ) {
 		if ( $this->debugMode ) {
 			$class = get_class( $this );
@@ -170,6 +203,7 @@ abstract class BagOStuff {
 
 	/**
 	 * Convert an optionally relative time to an absolute time
+	 * @param $exptime integer
 	 * @return int
 	 */
 	protected function convertExpiry( $exptime ) {
@@ -180,5 +214,3 @@ abstract class BagOStuff {
 		}
 	}
 }
-
-
-- 
2.20.1