Merge pull request #7849 from jrmajor/docs

Document `@psalm-yield`

docs/annotating_code/supported_annotations.md

@@ -31,7 +31,7 @@ The `@var` tag is supposed to only be used for properties. Psalm, taking a lead
 
 If `VariableReference` is provided, it should be of the form `$variable` or `$variable->property`. If used above an assignment, Psalm checks whether the `VariableReference` matches the variable being assigned. If they differ, Psalm will assign the `Type` to `VariableReference` and use it in the expression below.
 
-If no `VariableReference` is given, the annotation tells Psalm that the right hand side of the expression, whether an assignment or a return, is of type `Type`.
+If no `VariableReference` is given, the annotation tells Psalm that the right-hand side of the expression, whether an assignment or a return, is of type `Type`.
 
 ```php
 <?php
@@ -187,7 +187,7 @@ Used to mark a class, property or function as internal to a given namespace. Psa
 the PHPDoc `@internal` tag. For `@internal`, an issue is raised if the calling code is in a namespace completely
 unrelated to the namespace of the calling code, i.e. not sharing the first element of the namespace.
 
-In contrast for `@psalm-internal`, the docbloc line must specify a namespace. An issue is raised if the calling code
+In contrast for `@psalm-internal`, the docblock line must specify a namespace. An issue is raised if the calling code
 is not within the given namespace.
 
 ```php
@@ -551,7 +551,46 @@ Incidentally, it will change the inferred type for the following code:
         var_dump($a);
     }
 ```
-The type of `$a` is `array<array-key, int>` without `@no-named-arguments` but becomes `list<int>` with it, because it exclude the case where the offset would be a string with the name of the parameter
+The type of `$a` is `array<array-key, int>` without `@no-named-arguments` but becomes `list<int>` with it, because it excludes the case where the offset would be a string with the name of the parameter
+
+### `@psalm-yield`
+
+Used to specify the type of value which will be sent back to a generator when an annotated object instance is yielded.
+
+```php
+<?php
+/**
+ * @template-covariant TValue
+ * @psalm-yield TValue
+ */
+interface Promise {}
+
+/**
+ * @template-covariant TValue
+ * @template-implements Promise<TValue>
+ */
+class Success implements Promise {
+    /**
+     * @psalm-param TValue $value
+     */
+    public function __construct($value) {}
+}
+
+/**
+ * @return Promise<string>
+ */
+function fetch(): Promise {
+	return new Success('{"data":[]}');
+}
+
+function (): Generator {
+    $data = yield fetch();
+
+    // this is fine, Psalm knows that $data is a string
+    return json_decode($data);
+};
+```
+This annotation supports only generic types, meaning that e.g. `@psalm-yield string` would be ignored.
 
 ## Type Syntax
 

docs/annotating_code/type_syntax/array_types.md

@@ -27,7 +27,7 @@ Psalm has a few different ways to represent arrays in its type system:
 
 ## Generic arrays
 
-Psalm uses a syntax [borrowed from Java](https://en.wikipedia.org/wiki/Generics_in_Java) that allows you denote the types of both keys *and* values:
+Psalm uses a syntax [borrowed from Java](https://en.wikipedia.org/wiki/Generics_in_Java) that allows you to denote the types of both keys *and* values:
 ```php
 /** @return array<TKey, TValue> */
 ```

docs/annotating_code/typing_in_psalm.md

@@ -10,7 +10,7 @@ Psalm allows you to express a lot of complicated type information in docblocks.
 
 All docblock types are either [atomic types](type_syntax/atomic_types.md), [union types](type_syntax/union_types.md) or [intersection types](type_syntax/intersection_types.md).
 
-Additionally Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/latest/guide/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).
+Additionally, Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/latest/guide/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).
 
 ## Property declaration types vs Assignment typehints
 

docs/running_psalm/language_server.md

@@ -49,7 +49,7 @@ In the "Server definitions" tab you should add a definition for Psalm:
     - this should be an absolute path, not just `php`
  - Args: `vendor/bin/psalm-language-server` (on Windows use `vendor/vimeo/psalm/psalm-language-server`, or for a 'global' install '%APPDATA%' + `\Composer\vendor\vimeo\psalm\psalm-language-server`, where the '%APPDATA%' environment variable is probably something like `C:\Users\<homedir>\AppData\Roaming\`)
 
-In the "Timeouts" tab you can adjust the initialization timeout. This is important if you have a large project. You should set the "Init" value to the number of milliseconds you allow Psalm to scan your entire project and your project's dependencies. For opening a couple of projects that use large PHP frameworks, on a high end business laptop, try `240000` milliseconds for Init.
+In the "Timeouts" tab you can adjust the initialization timeout. This is important if you have a large project. You should set the "Init" value to the number of milliseconds you allow Psalm to scan your entire project and your project's dependencies. For opening a couple of projects that use large PHP frameworks, on a high-end business laptop, try `240000` milliseconds for Init.
 
 ## Sublime Text
 

tests/DocumentationTest.php

@@ -74,7 +74,6 @@ class DocumentationTest extends TestCase
      */
     private const WALL_OF_SHAME = [
         '@psalm-assert-untainted',
-        '@psalm-consistent-constructor',
         '@psalm-flow',
         '@psalm-generator-return',
         '@psalm-ignore-variable-method',
@@ -84,8 +83,6 @@ class DocumentationTest extends TestCase
         '@psalm-scope-this',
         '@psalm-seal-methods',
         '@psalm-stub-override',
-        '@psalm-taint-unescape',
-        '@psalm-yield',
     ];
 
     /** @var ProjectAnalyzer */