From 9546450cf242574efa8f5817a80ed040b3ade27d Mon Sep 17 00:00:00 2001
From: Mason Dechaineux <masonpcd@gmail.com>
Date: Fri, 31 May 2024 08:59:04 +1000
Subject: [PATCH] improve DataList and ArrayList docblock comments for PHPStorm
 (#11263)

addresses #11247
---
 src/ORM/ArrayList.php | 12 ++++++++++++
 src/ORM/DataList.php  | 11 +++++++++++
 2 files changed, 23 insertions(+)

diff --git a/src/ORM/ArrayList.php b/src/ORM/ArrayList.php
index f953ffb61..16fc11de4 100644
--- a/src/ORM/ArrayList.php
+++ b/src/ORM/ArrayList.php
@@ -137,6 +137,8 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
 
     /**
      * Return an array of the actual items that this ArrayList contains.
+     *
+     * @return array<T>
      */
     public function toArray()
     {
@@ -477,6 +479,8 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      * @example $list->sort('Name DESC'); // DESC sorting
      * @example $list->sort('Name', 'ASC');
      * @example $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
+     *
+     * @return static<T>
      */
     public function sort()
     {
@@ -589,6 +593,7 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      *
      * @param string $key
      * @param mixed $value
+     * @return T|null
      */
     public function find($key, $value)
     {
@@ -609,6 +614,8 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      * Also supports SearchFilter syntax
      * @example // include anyone with "sam" anywhere in their name
      *          $list = $list->filter('Name:PartialMatch', 'sam');
+     *
+     * @return static<T>
      */
     public function filter()
     {
@@ -635,6 +642,7 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      *          $list = $list->filterAny('Name:PartialMatch', 'sam');
      *
      * @param string|array See {@link filter()}
+     * @return static<T>
      */
     public function filterAny()
     {
@@ -656,6 +664,8 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      * Also supports SearchFilter syntax
      * @example // everyone except anyone with "sam" anywhere in their name
      *          $list = $list->exclude('Name:PartialMatch', 'sam');
+     *
+     * @return static<T>
      */
     public function exclude()
     {
@@ -829,6 +839,8 @@ class ArrayList extends ViewableData implements SS_List, Filterable, Sortable, L
      * Filter this list to only contain the given Primary IDs
      *
      * @param array $ids Array of integers, will be automatically cast/escaped.
+     *
+     * @return static<T>
      */
     public function byIDs($ids)
     {
diff --git a/src/ORM/DataList.php b/src/ORM/DataList.php
index d69c5a789..72ccacd71 100644
--- a/src/ORM/DataList.php
+++ b/src/ORM/DataList.php
@@ -322,6 +322,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Return a new DataList instance with the records returned in this query
      * restricted by a limit clause.
+     * @return static<T>
      */
     public function limit(?int $length, int $offset = 0): static
     {
@@ -364,6 +365,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * @example $list = $list->sort(['Name' => 'ASC', 'Age' => 'DESC']);
      * @example $list = $list->sort('MyRelation.MyColumn ASC')
      * @example $list->sort(null); // wipe any existing sort
+     *
+     * @return static<T>
      */
     public function sort(...$args): static
     {
@@ -480,6 +483,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * ->filter('Field:not', null) will generate '"Field" IS NOT NULL'
      *
      * @param string|array Escaped SQL statement. If passed as array, all keys and values will be escaped internally
+     * @return static<T>
      */
     public function filter()
     {
@@ -541,6 +545,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      *          // SQL: WHERE (("Name" IN ('bob', 'phil')) OR ("Age" IN ('21', '43'))
      *
      * @param string|array See {@link filter()}
+     * @return static<T>
      */
     public function filterAny()
     {
@@ -681,6 +686,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      *
      * @param string|array
      * @param string [optional]
+     * @return static<T>
      */
     public function exclude()
     {
@@ -824,6 +830,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Return an array of the actual items that this DataList contains at this stage.
      * This is when the query is actually executed.
+     * @return array<T>
      */
     public function toArray()
     {
@@ -1658,6 +1665,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * Returns the first item in this DataList
      *
      * The object returned is not cached, unlike {@link DataObject::get_one()}
+     * @return T|null
      */
     public function first()
     {
@@ -1676,6 +1684,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * Returns the last item in this DataList
      *
      * The object returned is not cached, unlike {@link DataObject::get_one()}
+     * @return T|null
      */
     public function last()
     {
@@ -1708,6 +1717,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      *
      * @param string $key
      * @param string $value
+     * @return T|null
      */
     public function find($key, $value)
     {
@@ -1736,6 +1746,7 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * Return the first DataObject with the given ID
      *
      * The object returned is not cached, unlike {@link DataObject::get_by_id()}
+     * @return T|null
      */
     public function byID($id)
     {