From f4f1a26cf994eeeadb484477486962e01c6e8019 Mon Sep 17 00:00:00 2001 From: Jeremiasz Major Date: Thu, 7 Apr 2022 21:43:12 +0200 Subject: [PATCH 1/3] Document `@psalm-yield` --- docs/annotating_code/supported_annotations.md | 39 +++++++++++++++++++ tests/DocumentationTest.php | 1 - 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/annotating_code/supported_annotations.md b/docs/annotating_code/supported_annotations.md index e1066f04de7..59f73cc3e37 100644 --- a/docs/annotating_code/supported_annotations.md +++ b/docs/annotating_code/supported_annotations.md @@ -553,6 +553,45 @@ Incidentally, it will change the inferred type for the following code: ``` The type of `$a` is `array` without `@no-named-arguments` but becomes `list` with it, because it exclude 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 + + */ +class Success implements Promise { + /** + * @psalm-param TValue $value + */ + public function __construct($value) {} +} + +/** + * @return Promise + */ +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 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). diff --git a/tests/DocumentationTest.php b/tests/DocumentationTest.php index 31c392d1aff..199cd2f6f9c 100644 --- a/tests/DocumentationTest.php +++ b/tests/DocumentationTest.php @@ -85,7 +85,6 @@ class DocumentationTest extends TestCase '@psalm-seal-methods', '@psalm-stub-override', '@psalm-taint-unescape', - '@psalm-yield', ]; /** @var ProjectAnalyzer */ From e1fe1161bdc8f717d7495369ba3ec5a152aea2b9 Mon Sep 17 00:00:00 2001 From: Jeremiasz Major Date: Thu, 7 Apr 2022 21:44:33 +0200 Subject: [PATCH 2/3] Remove documented annotations from wall of shame --- tests/DocumentationTest.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/DocumentationTest.php b/tests/DocumentationTest.php index 199cd2f6f9c..a3dbc93362a 100644 --- a/tests/DocumentationTest.php +++ b/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,7 +83,6 @@ class DocumentationTest extends TestCase '@psalm-scope-this', '@psalm-seal-methods', '@psalm-stub-override', - '@psalm-taint-unescape', ]; /** @var ProjectAnalyzer */ From 23ad8d6684fb44914f50fac318a11fdd4af98912 Mon Sep 17 00:00:00 2001 From: Jeremiasz Major Date: Thu, 7 Apr 2022 21:50:19 +0200 Subject: [PATCH 3/3] Fix typos --- docs/annotating_code/supported_annotations.md | 6 +++--- docs/annotating_code/type_syntax/array_types.md | 2 +- docs/annotating_code/typing_in_psalm.md | 2 +- docs/running_psalm/language_server.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/annotating_code/supported_annotations.md b/docs/annotating_code/supported_annotations.md index 59f73cc3e37..06077c3e705 100644 --- a/docs/annotating_code/supported_annotations.md +++ b/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 ` without `@no-named-arguments` but becomes `list` 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` without `@no-named-arguments` but becomes `list` with it, because it excludes the case where the offset would be a string with the name of the parameter ### `@psalm-yield` diff --git a/docs/annotating_code/type_syntax/array_types.md b/docs/annotating_code/type_syntax/array_types.md index 607cfe2ec73..bf289457525 100644 --- a/docs/annotating_code/type_syntax/array_types.md +++ b/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 */ ``` diff --git a/docs/annotating_code/typing_in_psalm.md b/docs/annotating_code/typing_in_psalm.md index 85e1211cc8e..4bb827f6696 100644 --- a/docs/annotating_code/typing_in_psalm.md +++ b/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 diff --git a/docs/running_psalm/language_server.md b/docs/running_psalm/language_server.md index cfeefb51d45..da756e0ad22 100644 --- a/docs/running_psalm/language_server.md +++ b/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\\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