From fe55a18b2e4bb079dcb96651482f3761c76d317a Mon Sep 17 00:00:00 2001
From: mason <masonpcd@gmail.com>
Date: Thu, 23 May 2024 16:35:41 +1000
Subject: [PATCH] improve DataList and ArrayList docblock comments for PHPStorm

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 f953ffb6176..16fc11de402 100644
--- a/src/ORM/ArrayList.php
+++ b/src/ORM/ArrayList.php
@@ -137,6 +137,8 @@ public function getIterator(): Traversable
 
     /**
      * Return an array of the actual items that this ArrayList contains.
+     *
+     * @return array<T>
      */
     public function toArray()
     {
@@ -477,6 +479,8 @@ protected function parseSortColumn($column, $direction = null)
      * @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 @@ public function canFilterBy($by)
      *
      * @param string $key
      * @param mixed $value
+     * @return T|null
      */
     public function find($key, $value)
     {
@@ -609,6 +614,8 @@ public function find($key, $value)
      * 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 @@ public function filter()
      *          $list = $list->filterAny('Name:PartialMatch', 'sam');
      *
      * @param string|array See {@link filter()}
+     * @return static<T>
      */
     public function filterAny()
     {
@@ -656,6 +664,8 @@ public function filterAny()
      * 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 @@ protected function normaliseFilterArgs($column, $value = null)
      * 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 d69c5a7899e..72ccacd7113 100644
--- a/src/ORM/DataList.php
+++ b/src/ORM/DataList.php
@@ -322,6 +322,7 @@ public function canFilterBy($fieldName)
     /**
      * 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 @@ public function distinct($value)
      * @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 @@ public function orderBy(string $orderBy): static
      * ->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 @@ public function addFilter($filterArray)
      *          // 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 @@ protected function isValidRelationName($field)
      *
      * @param string|array
      * @param string [optional]
+     * @return static<T>
      */
     public function exclude()
     {
@@ -824,6 +830,7 @@ public function rightJoin($table, $onClause, $alias = null, $order = 20, $parame
     /**
      * 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 @@ public function sum($fieldName)
      * 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 @@ public function first()
      * 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 @@ public function exists()
      *
      * @param string $key
      * @param string $value
+     * @return T|null
      */
     public function find($key, $value)
     {
@@ -1736,6 +1746,7 @@ public function byIDs($ids)
      * 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)
     {