PHPStan level 7: correct/tighten PHPDoc types

pinc/Activity.inc

@@ -74,7 +74,7 @@ class Activities
 
     /**
      * The return of this function is untyped for now (see the comment above `$_activities` for why).
-     * @return mixed[]
+     * @return array<string, mixed>
      */
     public static function get_all(): array
     {

pinc/CharSuites.inc

@@ -8,7 +8,12 @@ class CharSuiteNotEnabledException extends Exception
 class PickerSet
 {
     public string $name;
-    /** @var (?string)[][] */
+    /**
+     * @var array<string, (?string)[][]>
+     *    An associative array of named subsets.
+     *    Each subset is a list of rows (as displayed in the picker)
+     *    Each row is a list of characters (string) or empty spaces (null)
+     */
     private array $subsets;
     /** @var string[] */
     private array $titles;
@@ -25,7 +30,7 @@ class PickerSet
         }
     }
 
-    /** @return (?string)[][] */
+    /** @return array<string, (?string)[][]> */
     public function get_subsets(): array
     {
         return $this->subsets;

pinc/Project.inc

@@ -1926,7 +1926,7 @@ function project_get_auto_PPer(string $projectid): ?string
 /**
  * Does the user want anonymity for a given activity.
  *
- * @param 'cp'|'pm'|'pp'|'ip'|'tp' $activity
+ * @param 'cp'|'ec'|'pm'|'pp'|'ip'|'tp' $activity
  */
 function wants_anonymity(string $login_name, string $activity): bool
 {

pinc/ProjectState.inc

@@ -322,7 +322,7 @@ function sql_collator_for_project_state(string $state_column): string
 
 // XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
-/** @return string[] */
+/** @return ('posted'|'PPd'|'proofed'|'created')[] */
 function get_project_status_descriptors(): array
 {
     return ['posted', 'PPd', 'proofed', 'created'];

pinc/Round.inc

@@ -44,7 +44,7 @@ class Rounds extends Stages
 class Round extends Stage
 {
     public int $round_number;
-    /** @var array<string, string[]> */
+    /** @var array<string, 'ALL'|string[]> */
     public array $pi_tools;
     public ?int $daily_page_limit;
     /** @var array<string> */
@@ -56,7 +56,7 @@ class Round extends Stage
     public string $project_bad_state;
     public string $project_available_state;
     public string $project_complete_state;
-    /** @var ProjectState[] */
+    /** @var string[] */
     public array $project_states;
     public string $page_avail_state;
     public string $page_out_state;
@@ -75,7 +75,7 @@ class Round extends Stage
     /**
      * Round constructor
      *
-     * @param array<string, string|string[]> $pi_tools
+     * @param array<string, 'ALL'|string[]> $pi_tools
      *   A list of which tools should be available in the proofreading
      *   interface's toolbox when proofreading a page in this round.
      *   The format is:

pinc/graph_data.inc

@@ -362,7 +362,10 @@ function get_number_of_days_in_current_month(): int
     return $last_day['mday'];
 }
 
-/** @return GraphConfig */
+/**
+ * @param 'created'|'proofed'|'PPd'|'posted' $which
+ * @return GraphConfig
+ */
 function curr_month_proj(string $which): array
 {
     // Create "projects Xed per day" graph for current month
@@ -432,7 +435,10 @@ function array_subtract_first_from_each(array $arr): array
     return $result;
 }
 
-/** @return GraphConfig */
+/**
+ * @param 'created'|'proofed'|'PPd'|'posted' $which
+ * @return GraphConfig
+ */
 function cumulative_month_proj(string $which): array
 {
     // Create "projects Xed per day" graph for current month
@@ -490,7 +496,10 @@ function cumulative_month_proj(string $which): array
     ];
 }
 
-/** @return GraphConfig */
+/**
+ * @param 'created'|'proofed'|'PPd'|'posted' $which
+ * @return GraphConfig
+ */
 function total_proj_graph(string $which): array
 {
     //Create "projects Xed per day" graph for all known history
@@ -526,7 +535,10 @@ function total_proj_graph(string $which): array
     ];
 }
 
-/** @return GraphConfig */
+/**
+ * @param 'created'|'proofed'|'PPd'|'posted' $which
+ * @return GraphConfig
+ */
 function cumulative_total_proj_graph(string $which): array
 {
     // Create "cumulative projects Xed per day" graph for all days

pinc/misc.inc

@@ -295,9 +295,11 @@ function get_float_param(array $arr, string $key, ?float $default = null, ?float
  * This is the parent function of `get_integer_param()` and `get_float_param()`,
  * use those versions instead.
  *
+ * @param 'float'|'integer' $type
  * @param array<string, mixed> $arr
  *
- * @return ($allownull is true ? int|float|null : int|float)
+ * @return ($allownull is true ? ($type is 'integer' ? ?int : ?float)
+ *                             : ($type is 'integer' ? int  : float))
  *
  * @throws InvalidArgumentException
  *

pinc/page_table.inc

@@ -82,7 +82,7 @@ function get_rounds_to_display(Project $project): array
  * @param ?Round $work_round
  *   Round to limit a user's pages -- must be used with $page_selector set
  *   to a username.
- * @param ?string[] $only_rounds
+ * @param ?('OCR'|Round)[] $only_rounds
  *   Only return page details for a specific round, possible values are:
  *   * null - all rounds with data are returned
  *   * array of round objects and/or "OCR" - only these rounds are returned
@@ -101,6 +101,8 @@ function fetch_page_table_data(Project $project, $page_selector = null, ?Round $
         $rounds_to_display = get_rounds_to_display($project);
         $include_ocr = true;
     } else {
+        /** @var Round[] $rounds_to_display */
+        // Remove the magic "OCR" value, leaving only Round objects
         $rounds_to_display = array_unique(array_diff($only_rounds, ["OCR"]));
         $include_ocr = in_array("OCR", $only_rounds);
     }

pinc/showavailablebooks.inc

@@ -359,8 +359,8 @@ function show_projects_for_pool(Pool $pool, string $checkedout_or_available): vo
  *   The sort to use when one isn't specified by url-parameter or db-setting.
  * @param string $anchor
  *   The anchor on the page to jump to
- * @param object $stage
- *   Stage object (Round, Pool, or Stage)
+ * @param Round|Pool|Stage $stage
+ *   Stage object
  * @param string $optional_join_clause
  *   If needed. Default to "", but useful/necessary for SR & PP
  * @param string $optional_select_clause