historyblob: Improve param and property documentation

Also cast scalar types when needed

Change-Id: I88b17fe03d398df1ce2686aa0e223fc58e97e037

5 files changed, 20 insertions, 17 deletions

diff --git a/includes/externalstore/ExternalStoreDB.php b/includes/externalstore/ExternalStoreDB.php
index df55fa0439e4..e3ddfd3647ab 100644
--- a/includes/externalstore/ExternalStoreDB.php
+++ b/includes/externalstore/ExternalStoreDB.php
@@ -60,7 +60,7 @@ class ExternalStoreDB extends ExternalStoreMedium {
 	 * for concatenated storage if ConcatenatedGzipHistoryBlob was used.
 	 *
 	 * @param string $url
-	 * @return string|bool False if missing
+	 * @return string|false False if missing
 	 * @see ExternalStoreMedium::fetchFromURL()
 	 */
 	public function fetchFromURL( $url ) {
@@ -214,7 +214,7 @@ class ExternalStoreDB extends ExternalStoreMedium {
 
 	/**
 	 * @param array $server Primary DB server configuration array for LoadBalancer
-	 * @return string|bool Database domain ID or false
+	 * @return string|false Database domain ID or false
 	 */
 	private function getDomainId( array $server ) {
 		if ( $this->isDbDomainExplicit ) {
@@ -301,7 +301,7 @@ class ExternalStoreDB extends ExternalStoreMedium {
 	 * @param string $cluster
 	 * @param string $id
 	 * @param string $itemID
-	 * @return HistoryBlob|bool Returns false if missing
+	 * @return HistoryBlob|false Returns false if missing
 	 */
 	private function fetchBlob( $cluster, $id, $itemID ) {
 		/**
diff --git a/includes/historyblob/ConcatenatedGzipHistoryBlob.php b/includes/historyblob/ConcatenatedGzipHistoryBlob.php
index 3a17632f235c..af7953290d38 100644
--- a/includes/historyblob/ConcatenatedGzipHistoryBlob.php
+++ b/includes/historyblob/ConcatenatedGzipHistoryBlob.php
@@ -25,16 +25,19 @@
  * Improves compression ratio by concatenating like objects before gzipping
  */
 class ConcatenatedGzipHistoryBlob implements HistoryBlob {
+	/** @var int */
 	public $mVersion = 0;
+	/** @var bool */
 	public $mCompressed = false;
-	/**
-	 * @var array|string
-	 * @fixme Why are some methods treating it as an array, and others as a string, unconditionally?
-	 */
+	/** @var string[]|string Array if uncompressed, string if compressed */
 	public $mItems = [];
+	/** @var string */
 	public $mDefaultHash = '';
+	/** @var int */
 	public $mSize = 0;
+	/** @var int */
 	public $mMaxSize = 10000000;
+	/** @var int */
 	public $mMaxCount = 100;
 
 	public function __construct() {
@@ -60,7 +63,7 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob {
 
 	/**
 	 * @param string $hash
-	 * @return array|bool
+	 * @return string|false
 	 */
 	public function getItem( $hash ) {
 		$this->uncompress();
@@ -81,7 +84,7 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob {
 	}
 
 	/**
-	 * @return array|bool
+	 * @return string|false
 	 */
 	public function getText() {
 		$this->uncompress();
diff --git a/includes/historyblob/DiffHistoryBlob.php b/includes/historyblob/DiffHistoryBlob.php
index b31b1d5c5408..3330ffa95bdd 100644
--- a/includes/historyblob/DiffHistoryBlob.php
+++ b/includes/historyblob/DiffHistoryBlob.php
@@ -27,7 +27,7 @@ use Wikimedia\AtEase\AtEase;
  * Requires xdiff 1.5+ and zlib
  */
 class DiffHistoryBlob implements HistoryBlob {
-	/** @var array Uncompressed item cache */
+	/** @var string[] Uncompressed item cache */
 	public $mItems = [];
 
 	/** @var int Total uncompressed size */
@@ -46,11 +46,11 @@ class DiffHistoryBlob implements HistoryBlob {
 	/** @var array The diff map, see above */
 	public $mDiffMap;
 
-	/** @var int The key for getText()
+	/** @var string The key for getText()
 	 */
 	public $mDefaultKey;
 
-	/** @var string Compressed storage */
+	/** @var string|null Compressed storage */
 	public $mCompressed;
 
 	/** @var bool True if the object is locked against further writes */
@@ -79,7 +79,7 @@ class DiffHistoryBlob implements HistoryBlob {
 	/**
 	 * @throws MWException
 	 * @param string $text
-	 * @return int
+	 * @return string
 	 */
 	public function addItem( $text ) {
 		if ( $this->mFrozen ) {
@@ -89,7 +89,7 @@ class DiffHistoryBlob implements HistoryBlob {
 		$this->mItems[] = $text;
 		$this->mSize += strlen( $text );
 		$this->mDiffs = null; // later
-		return count( $this->mItems ) - 1;
+		return (string)( count( $this->mItems ) - 1 );
 	}
 
 	/**
@@ -97,7 +97,7 @@ class DiffHistoryBlob implements HistoryBlob {
 	 * @return string
 	 */
 	public function getItem( $key ) {
-		return $this->mItems[$key];
+		return $this->mItems[(int)$key];
 	}
 
 	/**
diff --git a/includes/historyblob/HistoryBlob.php b/includes/historyblob/HistoryBlob.php
index f9ead88f7679..8328020c2d35 100644
--- a/includes/historyblob/HistoryBlob.php
+++ b/includes/historyblob/HistoryBlob.php
@@ -61,7 +61,7 @@ interface HistoryBlob {
 	/**
 	 * Get default text.
 	 *
-	 * @return string
+	 * @return string|false
 	 */
 	public function getText();
 }
diff --git a/includes/historyblob/HistoryBlobCurStub.php b/includes/historyblob/HistoryBlobCurStub.php
index 68cf5a2a1080..4bae5e71c387 100644
--- a/includes/historyblob/HistoryBlobCurStub.php
+++ b/includes/historyblob/HistoryBlobCurStub.php
@@ -50,7 +50,7 @@ class HistoryBlobCurStub {
 	}
 
 	/**
-	 * @return string|bool
+	 * @return string|false
 	 */
 	public function getText() {
 		$dbr = wfGetDB( DB_REPLICA );