[statistics] Add type annotations and a couple comments

2 files changed, 35 insertions, 8 deletions

diff --git a/modules-available/statistics/inc/statisticsfilter.inc.php b/modules-available/statistics/inc/statisticsfilter.inc.php
index 03a66b25..a4e96294 100644
--- a/modules-available/statistics/inc/statisticsfilter.inc.php
+++ b/modules-available/statistics/inc/statisticsfilter.inc.php
@@ -61,11 +61,28 @@ abstract class StatisticsFilter
 		return ($this->ops === self::OP_ORDINAL || $this->ops === self::OP_FUZZY_ORDINAL) ? 'int' : 'string';
 	}
 
-	/* returns a where clause and adds needed operators to the passed arrays */
+	/**
+	 * To be called by DatabaseFilter::whereClause() when building actual query.
+	 * @param string $operator operator to use
+	 * @param string[]|string $argument argument to compare against
+	 * @param string[] $args assoc array to add parametrized version of $argument to
+	 * @param string[] $joins any optional joins can be added to this array
+	 * @return string where clause
+	 */
 	public abstract function whereClause(string $operator, $argument, array &$args, array &$joins): string;
 
+	/**
+	 * Called to get an instance of DatabaseFilter that binds the given $op and $argument to this filter.
+	 * @param string $op
+	 * @param string[]|string $argument
+	 * @return DatabaseFilter
+	 */
 	public function bind(string $op, $argument): DatabaseFilter { return new DatabaseFilter($this, $op, $argument); }
 
+	/**
+	 * Check if given $operator is valid for this filter. Throws error and halts if not.
+	 * @return void
+	 */
 	public final function validateOperator(string $operator)
 	{
 		if (empty($this->ops))
@@ -421,7 +438,7 @@ class RuntimeStatisticsFilter extends StatisticsFilter
 abstract class GbToMbRangeStatisticsFilter extends StatisticsFilter
 {
 
-	protected function rangeClause(string $operator, $argument, array $fuzzyVals)
+	protected function rangeClause(string $operator, $argument, array $fuzzyVals): string
 	{
 		if ($operator === '~' || $operator === '!~') {
 			$lower = (int)floor(StatisticsFilter::findBestValue($fuzzyVals, (int)$argument, false) * 1024 - 500);
@@ -617,6 +634,9 @@ class DatabaseFilter
 	public $op;
 	public $argument;
 
+	/**
+	 * Called by StatisticsFilter::bind().
+	 */
 	public function __construct(StatisticsFilter $inst, string $op, $argument)
 	{
 		$inst->validateOperator($op);
@@ -624,12 +644,19 @@ class DatabaseFilter
 		$this->op = $op;
 		$this->argument = $argument;
 	}
-	public function whereClause(array &$args, array &$joins)
+
+	/**
+	 * Called from StatisticsFilterSet::makeFragments() to build the final query.
+	 * @param array $args
+	 * @param array $joins
+	 * @return string
+	 */
+	public function whereClause(array &$args, array &$joins): string
 	{
 		return $this->inst->whereClause($this->op, $this->argument, $args, $joins);
 	}
 
-	public function isClass($what)
+	public function isClass(string $what): bool
 	{
 		return get_class($this->inst) === $what;
 	}
diff --git a/modules-available/statistics/inc/statisticsfilterset.inc.php b/modules-available/statistics/inc/statisticsfilterset.inc.php
index a38f9d3f..e4117a8c 100644
--- a/modules-available/statistics/inc/statisticsfilterset.inc.php
+++ b/modules-available/statistics/inc/statisticsfilterset.inc.php
@@ -38,7 +38,7 @@ class StatisticsFilterSet
 		$this->cache = compact('where', 'join', 'args');
 	}
 	
-	public function isNoId44Filter()
+	public function isNoId44Filter(): bool
 	{
 		$filter = $this->hasFilter('Id44GbStatisticsFilter');
 		return $filter !== false && $filter->argument == 0;
@@ -57,7 +57,7 @@ class StatisticsFilterSet
 	 * @param string $type filter type (class name)
 	 * @return false|DatabaseFilter The filter, false if not found
 	 */
-	public function hasFilter($type)
+	public function hasFilter(string $type)
 	{
 		foreach ($this->filters as $filter) {
 			if ($filter->isClass($type)) {
@@ -71,7 +71,7 @@ class StatisticsFilterSet
 	 * @param string $type filter type key/id
 	 * @return false|DatabaseFilter The filter, false if not found
 	 */
-	public function hasFilterKey($type)
+	public function hasFilterKey(string $type)
 	{
 		if (isset($this->filters[$type]))
 			return $this->filters[$type];
@@ -85,7 +85,7 @@ class StatisticsFilterSet
 	 * @param string $permission permission to use
 	 * @return bool false if no permission for any location, true otherwise
 	 */
-	public function setAllowedLocationsFromPermission($permission)
+	public function setAllowedLocationsFromPermission(string $permission): bool
 	{
 		if (!Module::isAvailable('locations'))
 			return true;