WRStats: Improve various docs

Change-Id: I3c3e9c155cedc347a600cad16301c484e50b6f90

14 files changed, 45 insertions, 53 deletions

diff --git a/includes/libs/WRStats/ArrayStatsStore.php b/includes/libs/WRStats/ArrayStatsStore.php
index c1d394649a9a..a801504defa2 100644
--- a/includes/libs/WRStats/ArrayStatsStore.php
+++ b/includes/libs/WRStats/ArrayStatsStore.php
@@ -3,7 +3,7 @@
 namespace Wikimedia\WRStats;
 
 /**
- * In memory stats store.
+ * In-memory stats store.
  */
 class ArrayStatsStore implements StatsStore {
 	/**
diff --git a/includes/libs/WRStats/GlobalEntityKey.php b/includes/libs/WRStats/GlobalEntityKey.php
index 12f96df58477..f607b30e542d 100644
--- a/includes/libs/WRStats/GlobalEntityKey.php
+++ b/includes/libs/WRStats/GlobalEntityKey.php
@@ -3,7 +3,7 @@
 namespace Wikimedia\WRStats;
 
 /**
- * Entity key with global=true
+ * Entity key with isGlobal=true
  *
  * @newable
  * @since 1.39
diff --git a/includes/libs/WRStats/LimitBatch.php b/includes/libs/WRStats/LimitBatch.php
index 90a7499e01e9..3758a40fc6e3 100644
--- a/includes/libs/WRStats/LimitBatch.php
+++ b/includes/libs/WRStats/LimitBatch.php
@@ -18,8 +18,7 @@ class LimitBatch {
 	private $operations = [];
 
 	/**
-	 * @internal
-	 *
+	 * @internal Use WRStatsFactory::createRateLimiter()->createBatch() instead
 	 * @param WRStatsRateLimiter $limiter
 	 * @param int $defaultAmount
 	 */
@@ -76,9 +75,8 @@ class LimitBatch {
 	private function queueOp( $type, $entity, $amount ) {
 		$amount ??= $this->defaultAmount;
 		if ( isset( $this->operations[$type] ) ) {
-			throw new WRStatsError( __METHOD__ .
-				': cannot queue multiple actions of the same type, ' .
-				'since the result array is indexed by type' );
+			throw new WRStatsError( 'Cannot queue multiple actions of the same type, ' .
+				'because the result array is indexed by type' );
 		}
 		$this->operations[$type] = new LimitOperation( $type, $entity, $amount );
 	}
diff --git a/includes/libs/WRStats/LimitBatchResult.php b/includes/libs/WRStats/LimitBatchResult.php
index 796968489a54..cb01f017192a 100644
--- a/includes/libs/WRStats/LimitBatchResult.php
+++ b/includes/libs/WRStats/LimitBatchResult.php
@@ -15,8 +15,7 @@ class LimitBatchResult {
 	private $allowed;
 
 	/**
-	 * @internal
-	 *
+	 * @internal Use WRStatsFactory::createRateLimiter() instead
 	 * @param LimitOperationResult[] $results
 	 */
 	public function __construct( $results ) {
diff --git a/includes/libs/WRStats/LimitCondition.php b/includes/libs/WRStats/LimitCondition.php
index 4d660ee0cfb3..6fc02b391e3e 100644
--- a/includes/libs/WRStats/LimitCondition.php
+++ b/includes/libs/WRStats/LimitCondition.php
@@ -21,8 +21,7 @@ class LimitCondition {
 		$this->limit = (int)$limit;
 		$this->window = +$window;
 		if ( $this->window <= 0 ) {
-			throw new WRStatsError( __METHOD__ .
-				': window must be positive' );
+			throw new WRStatsError( 'Condition window must be positive' );
 		}
 	}
 
diff --git a/includes/libs/WRStats/LimitOperation.php b/includes/libs/WRStats/LimitOperation.php
index c00470d3629b..860dd104336d 100644
--- a/includes/libs/WRStats/LimitOperation.php
+++ b/includes/libs/WRStats/LimitOperation.php
@@ -3,7 +3,11 @@
 namespace Wikimedia\WRStats;
 
 /**
- * Class representing one item in a limit batch
+ * One item in a LimitBatch.
+ *
+ * To perform a single operation, it is generally recommendeded to use
+ * the simpler interface of WRStatsRateLimiter::peek(), ::incr(), and
+ * ::tryIncr() instead of constructing LimitOperation objects.
  *
  * @newable
  * @since 1.39
diff --git a/includes/libs/WRStats/LocalEntityKey.php b/includes/libs/WRStats/LocalEntityKey.php
index dd7b0a3725cb..89096e738133 100644
--- a/includes/libs/WRStats/LocalEntityKey.php
+++ b/includes/libs/WRStats/LocalEntityKey.php
@@ -3,7 +3,7 @@
 namespace Wikimedia\WRStats;
 
 /**
- * Entity key with global=false
+ * Entity key with isGlobal=false
  *
  * @newable
  * @since 1.39
diff --git a/includes/libs/WRStats/MetricSpec.php b/includes/libs/WRStats/MetricSpec.php
index 723f5dec6686..6e7c966ef0b8 100644
--- a/includes/libs/WRStats/MetricSpec.php
+++ b/includes/libs/WRStats/MetricSpec.php
@@ -15,7 +15,7 @@ class MetricSpec {
 	public $type;
 	/** @var float|int */
 	public $resolution;
-	/** @var SequenceSpec[] Sequences in ascending order of expiry */
+	/** @var array<string,SequenceSpec> Sequences in ascending order of expiry */
 	public $sequences;
 
 	/**
@@ -26,19 +26,17 @@ class MetricSpec {
 		$this->resolution = $spec['resolution'] ?? self::DEFAULT_RESOLUTION;
 		foreach ( [ 'timeStep', 'expiry' ] as $var ) {
 			if ( isset( $spec[$var] ) ) {
-				throw new WRStatsError( __METHOD__ .
-					": $var must be specified in the sequences array" );
+				throw new WRStatsError( "$var must be in the sequences array" );
 			}
 		}
 		$seqArrays = $spec['sequences'] ?? [];
-		if ( !count( $seqArrays ) ) {
+		if ( !$seqArrays ) {
 			$seqArrays = [ [] ];
 		}
 		$sequences = [];
 		foreach ( $seqArrays as $i => $seqArray ) {
 			if ( !is_array( $seqArray ) ) {
-				throw new WRStatsError( __METHOD__ .
-					': sequences is supposed to be an array of arrays' );
+				throw new WRStatsError( 'sequences must be an array of arrays' );
 			}
 			$seqSpec = new SequenceSpec( $seqArray );
 			while ( isset( $sequences[$seqSpec->name] ) ) {
diff --git a/includes/libs/WRStats/RatePromise.php b/includes/libs/WRStats/RatePromise.php
index d45041b46542..047a359e5217 100644
--- a/includes/libs/WRStats/RatePromise.php
+++ b/includes/libs/WRStats/RatePromise.php
@@ -26,8 +26,7 @@ class RatePromise {
 	private $total;
 
 	/**
-	 * @internal Constructed by WRStatsReader
-	 *
+	 * @internal Use via WRStatsReader from WRStatsFactory::createReader instead
 	 * @param WRStatsReader $reader
 	 * @param string $name
 	 * @param EntityKey $entity
diff --git a/includes/libs/WRStats/StatsStore.php b/includes/libs/WRStats/StatsStore.php
index c0e8893b2742..d950c6eef496 100644
--- a/includes/libs/WRStats/StatsStore.php
+++ b/includes/libs/WRStats/StatsStore.php
@@ -3,7 +3,7 @@
 namespace Wikimedia\WRStats;
 
 /**
- * The narrow interface WRStats needs into a memcached-like key-value store.
+ * Narrow interface for WRStatsFactory to a memcached-like key-value store.
  *
  * @since 1.39
  */
@@ -11,8 +11,8 @@ interface StatsStore {
 	/**
 	 * Construct a string key from its components
 	 *
-	 * @param array $prefix The prefix components.
-	 * @param array $internals The internal components.
+	 * @param string[] $prefix The prefix components.
+	 * @param array<string|int> $internals The internal components.
 	 * @param EntityKey $entity The entity components. If $entity->isGlobal()
 	 *   is true, the key as a whole should be treated as global.
 	 * @return string
diff --git a/includes/libs/WRStats/WRStatsFactory.php b/includes/libs/WRStats/WRStatsFactory.php
index 25a983520c6d..c69d263ad3d5 100644
--- a/includes/libs/WRStats/WRStatsFactory.php
+++ b/includes/libs/WRStats/WRStatsFactory.php
@@ -3,7 +3,7 @@
 namespace Wikimedia\WRStats;
 
 /**
- * A factory for WRStats readers and writers.
+ * The main entry point to WRStats, for creating readers and writers.
  *
  * Readers and writers should generally be used for a batch and then discarded.
  * Factory objects can be retained indefinitely.
diff --git a/includes/libs/WRStats/WRStatsRateLimiter.php b/includes/libs/WRStats/WRStatsRateLimiter.php
index 1b915e3ce868..2b9e0313eb53 100644
--- a/includes/libs/WRStats/WRStatsRateLimiter.php
+++ b/includes/libs/WRStats/WRStatsRateLimiter.php
@@ -4,6 +4,8 @@ namespace Wikimedia\WRStats;
 
 /**
  * A rate limiter with a WRStats backend
+ *
+ * @since 1.39
  */
 class WRStatsRateLimiter {
 	/** @var StatsStore */
@@ -21,10 +23,7 @@ class WRStatsRateLimiter {
 	public const BUCKET_COUNT = 30;
 
 	/**
-	 * @internal Use WRStatsFactory
-	 *
-	 * @see WRStatsFactory::createRateLimiter for full parameter documentation.
-	 *
+	 * @internal Use WRStatsFactory::createRateLimiter instead
 	 * @param StatsStore $store
 	 * @param LimitCondition[] $conditions
 	 * @param string|string[] $prefix
@@ -102,8 +101,7 @@ class WRStatsRateLimiter {
 			$name = $operation->condName;
 			$cond = $this->conditions[$name] ?? null;
 			if ( $cond === null ) {
-				throw new WRStatsError( __METHOD__ .
-					": unrecognized metric \"$name\"" );
+				throw new WRStatsError( "Unrecognized metric \"$name\"" );
 			}
 			if ( !isset( $rates[$name] ) ) {
 				$range = $reader->latest( $cond->window );
diff --git a/includes/libs/WRStats/WRStatsReader.php b/includes/libs/WRStats/WRStatsReader.php
index 1206fdbf560c..be97fcfb232b 100644
--- a/includes/libs/WRStats/WRStatsReader.php
+++ b/includes/libs/WRStats/WRStatsReader.php
@@ -11,7 +11,7 @@ namespace Wikimedia\WRStats;
 class WRStatsReader {
 	/** @var StatsStore */
 	private $store;
-	/** @var MetricSpec[] */
+	/** @var array<string,MetricSpec> */
 	private $metricSpecs;
 	/** @var string[] */
 	private $prefixComponents;
@@ -23,10 +23,9 @@ class WRStatsReader {
 	private $cachedValues = [];
 
 	/**
-	 * @internal
-	 *
+	 * @internal Use WRStatsFactory::createReader instead
 	 * @param StatsStore $store
-	 * @param array $specs
+	 * @param array<string,array> $specs
 	 * @param string|string[] $prefix
 	 */
 	public function __construct( StatsStore $store, $specs, $prefix ) {
@@ -77,7 +76,7 @@ class WRStatsReader {
 	public function getRate( $metricName, ?EntityKey $entity, TimeRange $range ) {
 		$metricSpec = $this->metricSpecs[$metricName] ?? null;
 		if ( $metricSpec === null ) {
-			throw new WRStatsError( __METHOD__ . ": Unrecognised metric \"$metricName\"" );
+			throw new WRStatsError( "Unrecognised metric \"$metricName\"" );
 		}
 		$entity ??= new LocalEntityKey;
 		$now = $this->now();
@@ -158,8 +157,7 @@ class WRStatsReader {
 	}
 
 	/**
-	 * @internal Method for promise resolution
-	 *
+	 * @internal Utility for resolution in RatePromise
 	 * @param string $metricName
 	 * @param EntityKey $entity
 	 * @param MetricSpec $metricSpec
@@ -231,8 +229,8 @@ class WRStatsReader {
 	 * Resolve a batch of RatePromise objects, returning their counter totals,
 	 * indexed as in the input array.
 	 *
-	 * @param RatePromise[] $rates
-	 * @return array<string,float|int>
+	 * @param array<mixed,RatePromise> $rates
+	 * @return array<mixed,float|int>
 	 */
 	public function total( $rates ) {
 		$result = [];
@@ -245,8 +243,8 @@ class WRStatsReader {
 	/**
 	 * Resolve a batch of RatePromise objects, returning their per-second rates.
 	 *
-	 * @param RatePromise[] $rates
-	 * @return float[]
+	 * @param array<mixed,RatePromise> $rates
+	 * @return array<mixed,float>
 	 */
 	public function perSecond( $rates ) {
 		$result = [];
@@ -259,8 +257,8 @@ class WRStatsReader {
 	/**
 	 * Resolve a batch of RatePromise objects, returning their per-minute rates.
 	 *
-	 * @param RatePromise[] $rates
-	 * @return float[]
+	 * @param array<mixed,RatePromise> $rates
+	 * @return array<mixed,float>
 	 */
 	public function perMinute( $rates ) {
 		$result = [];
@@ -273,8 +271,8 @@ class WRStatsReader {
 	/**
 	 * Resolve a batch of RatePromise objects, returning their per-hour rates.
 	 *
-	 * @param RatePromise[] $rates
-	 * @return float[]
+	 * @param array<mixed,RatePromise> $rates
+	 * @return array<mixed,float>
 	 */
 	public function perHour( $rates ) {
 		$result = [];
@@ -287,8 +285,8 @@ class WRStatsReader {
 	/**
 	 * Resolve a batch of RatePromise objects, returning their per-day rates.
 	 *
-	 * @param RatePromise[] $rates
-	 * @return float[]
+	 * @param array<mixed,RatePromise> $rates
+	 * @return array<mixed,float>
 	 */
 	public function perDay( $rates ) {
 		$result = [];
diff --git a/includes/libs/WRStats/WRStatsWriter.php b/includes/libs/WRStats/WRStatsWriter.php
index 6a5289efdebe..8ed2dc8d3c6b 100644
--- a/includes/libs/WRStats/WRStatsWriter.php
+++ b/includes/libs/WRStats/WRStatsWriter.php
@@ -11,7 +11,7 @@ namespace Wikimedia\WRStats;
 class WRStatsWriter {
 	/** @var StatsStore */
 	private $store;
-	/** @var MetricSpec[] */
+	/** @var array<string,MetricSpec> */
 	private $metricSpecs;
 	/** @var float[][] Values indexed by TTL and storage key */
 	private $queuedValues = [];
@@ -21,10 +21,9 @@ class WRStatsWriter {
 	private $prefixComponents;
 
 	/**
-	 * @internal
-	 *
+	 * @internal Use WRStatsFactory::createWriter instead
 	 * @param StatsStore $store
-	 * @param array $specs
+	 * @param array<string,array> $specs
 	 * @param string|string[] $prefix
 	 */
 	public function __construct( StatsStore $store, $specs, $prefix ) {
@@ -51,7 +50,7 @@ class WRStatsWriter {
 		$metricSpec = $this->metricSpecs[$name] ?? null;
 		$entity ??= new LocalEntityKey;
 		if ( $metricSpec === null ) {
-			throw new WRStatsError( __METHOD__ . ": Unrecognised metric \"$name\"" );
+			throw new WRStatsError( "Unrecognised metric \"$name\"" );
 		}
 		$res = $metricSpec->resolution;
 		$scaledValue = $value / $res;