From d6386b9a1fd998ac41f0f9da7f0baaa9e347e487 Mon Sep 17 00:00:00 2001
From: Daniil Gentili <daniil@daniil.it>
Date: Sat, 3 Dec 2022 17:35:38 +0100
Subject: [PATCH] Clarify docs

---
 UPGRADING.md                            | 2 +-
 src/Psalm/Type/Atomic/TCallableList.php | 2 +-
 src/Psalm/Type/Atomic/TList.php         | 4 ++++
 src/Psalm/Type/Atomic/TNonEmptyList.php | 4 ++++
 4 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index 489a82095..fcbe714b1 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -2,7 +2,7 @@
 ## Changed
 
 - [BC] Switched the internal representation of `list<T>` and `non-empty-list<T>` from the TList and TNonEmptyList classes to an unsealed list shape: the TList, TNonEmptyList and TCallableList classes were removed.
-  Nothing will change for users: `list<T>` and `non-empty-list<T>` syntax will remain supported and its semantics unchanged.
+  Nothing will change for users: the `list<T>` and `non-empty-list<T>` syntax will remain supported and its semantics unchanged.
   Psalm 5 already deprecates the `TList`, `TNonEmptyList` and `TCallableList` classes: use `\Psalm\Type::getListAtomic`, `\Psalm\Type::getNonEmptyListAtomic` and `\Psalm\Type::getCallableListAtomic` to instantiate list atomics, or directly instantiate TKeyedArray objects with `is_list=true` where appropriate.
 
 - [BC] The only optional boolean parameter of `TKeyedArray::getGenericArrayType` was removed, and was replaced with a string parameter with a different meaning.
diff --git a/src/Psalm/Type/Atomic/TCallableList.php b/src/Psalm/Type/Atomic/TCallableList.php
index 92ddfac22..c0321d220 100644
--- a/src/Psalm/Type/Atomic/TCallableList.php
+++ b/src/Psalm/Type/Atomic/TCallableList.php
@@ -7,7 +7,7 @@ use Psalm\Type;
 use function array_fill;
 
 /**
- * @deprecated Will be removed in Psalm v6, please use TKeyedArrays with is_list=true instead.
+ * @deprecated Will be removed in Psalm v6, please use TCallableKeyedArrays with is_list=true instead.
  *
  * Denotes a list that is _also_ `callable`.
  * @psalm-immutable
diff --git a/src/Psalm/Type/Atomic/TList.php b/src/Psalm/Type/Atomic/TList.php
index 6445ec85f..888284f52 100644
--- a/src/Psalm/Type/Atomic/TList.php
+++ b/src/Psalm/Type/Atomic/TList.php
@@ -16,6 +16,10 @@ use function get_class;
 /**
  * @deprecated Will be removed in Psalm v6, please use TKeyedArrays with is_list=true instead.
  *
+ * You may also use the \Psalm\Type::getListAtomic shortcut, which creates unsealed list-like shaped arrays
+ * with all elements optional, semantically equivalent to a TList.
+ *
+ *
  * Represents an array that has some particularities:
  * - its keys are integers
  * - they start at 0
diff --git a/src/Psalm/Type/Atomic/TNonEmptyList.php b/src/Psalm/Type/Atomic/TNonEmptyList.php
index fa39fe6f3..a87f7da89 100644
--- a/src/Psalm/Type/Atomic/TNonEmptyList.php
+++ b/src/Psalm/Type/Atomic/TNonEmptyList.php
@@ -10,6 +10,10 @@ use function array_fill;
 /**
  * @deprecated Will be removed in Psalm v6, please use TKeyedArrays with is_list=true instead.
  *
+ * You may also use the \Psalm\Type::getNonEmptyListAtomic shortcut, which creates unsealed list-like shaped arrays
+ * with one non-optional element, semantically equivalent to a TNonEmptyList.
+ *
+ *
  * Represents a non-empty list
  * @psalm-immutable
  */