Add documentation for lists

docs/annotating_code/type_syntax/array_types.md

@@ -20,12 +20,7 @@ $a = ['name' => 'Psalm', 'type' => 'tool'];
 
 PHP treats all these arrays the same, essentially (though there are some optimisations under the hood for the first case).
 
-## PHPDoc syntax
-
-PHPDoc [allows you to specify](https://phpdoc.org/docs/latest/references/phpdoc/types.html#arrays) the  type of values the array holds with the annotation:
-```php
-/** @return ValueType[] */
-```
+Psalm has a few different ways to represent arrays in its type system:
 
 ## Generic arrays
 
@@ -36,6 +31,61 @@ Psalm uses a syntax [borrowed from Java](https://en.wikipedia.org/wiki/Generics_
 
 You can also specify that an array is non-empty with the special type `non-empty-array<TKey, TValue>`.
 
+### PHPDoc syntax
+
+PHPDoc [allows you to specify](https://phpdoc.org/docs/latest/references/phpdoc/types.html#arrays) the  type of values a generic array holds with the annotation:
+```php
+/** @return ValueType[] */
+```
+
+In Psalm this annotation is equivalent to `array<int|string, ValueType>`.
+
+Generic arrays encompass both _associative arrays_ and _lists_.
+
+## Lists
+
+(Psalm 3.6+)
+
+Psalm supports a `list` type that represents continuous, integer-indexed arrays like `["red", "yellow", "blue"]` .
+
+These arrays have the property `$arr === array_values($arr)`, and represent a large percentage of all array usage in PHP applications.
+
+A `list` type is of the form `list<SomeType>`,  where `SomeType` is any permitted [union type](union_types.md) supported by Psalm.
+
+- `list` is a subtype of `array<int, mixed>`
+- `list<Foo>` is a subtype of `array<int, Foo>`.
+
+List types show their value in a few ways:
+
+```php
+/**
+ * @param array<int, string> $arr
+ */
+function takesArray(array $arr) : void {
+  if ($arr) {
+     // this index may not be set
+    echo $arr[0];
+  }
+}
+
+/**
+ * @psalm-param list<string> $arr
+ */
+function takesList(array $arr) : void {
+  if ($arr) {
+    // list indexes always start from zero,
+    // so a non-empty list will have an element here
+    echo $arr[0];
+  }
+}
+
+takesArray(["hello"]); // this is fine
+takesArray([1 => "hello"]); // would trigger bug, without warning
+
+takesList(["hello"]); // this is fine
+takesList([1 => "hello"]); // triggers warning in Psalm
+```
+
 ## Object-like arrays
 
 Psalm supports a special format for arrays where the key offsets are known: object-like arrays.