danog/psalm
1
0
Fork 0
mirror of https://github.com/danog/psalm.git synced 2024-11-30 04:39:00 +01:00
Code Issues Projects Releases Wiki Activity

Add changes from @nickr

Browse Source
This commit is contained in:
Matthew Brown 2018-01-30 11:31:17 -05:00 committed by GitHub
parent 6b4fb62d0d
commit 10377ca0d3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/supported_annotations.md
View File

@ -20,12 +20,19 @@ Psalm supports a wide range of docblock annotations.
Psalm uses the following PHPDoc tags to understand your code: Psalm uses the following PHPDoc tags to understand your code:
- [`@var`](https://docs.phpdoc.org/references/phpdoc/tags/var.html) - [`@var`](https://docs.phpdoc.org/references/phpdoc/tags/var.html)
Used for specifying the types of properties and variables
- [`@return`](https://docs.phpdoc.org/references/phpdoc/tags/return.html) - [`@return`](https://docs.phpdoc.org/references/phpdoc/tags/return.html)
Used for specifying the return types of functions, methods and closures
- [`@param`](https://docs.phpdoc.org/references/phpdoc/tags/param.html) - [`@param`](https://docs.phpdoc.org/references/phpdoc/tags/param.html)
Used for specifying types of parameters passed to functions, methods and closures
- [`@property`](https://docs.phpdoc.org/references/phpdoc/tags/property.html) - [`@property`](https://docs.phpdoc.org/references/phpdoc/tags/property.html)
Used to specify what properties can be accessed on an object that uses `__get` and `__set`
- [`@property-read`](https://docs.phpdoc.org/references/phpdoc/tags/property-read.html) - [`@property-read`](https://docs.phpdoc.org/references/phpdoc/tags/property-read.html)
Used to specify what properties can be read on object that uses `__get`
- [`@property-write`](https://docs.phpdoc.org/references/phpdoc/tags/property-write.html) - [`@property-write`](https://docs.phpdoc.org/references/phpdoc/tags/property-write.html)
Used to specify what properties can be written on object that uses `__set`
- [`@deprecated`](https://docs.phpdoc.org/references/phpdoc/tags/deprecated.html) - [`@deprecated`](https://docs.phpdoc.org/references/phpdoc/tags/deprecated.html)
Used to mark functions, methods, classes and interfaces as being deprecated
### Off-label usage of the `@var` tag ### Off-label usage of the `@var` tag
@ -33,7 +40,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 `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 RHS 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
/** @var string */ /** @var string */
@ -54,7 +61,7 @@ There are a number of custom tags that determine how Psalm treats your code.
### `@psalm-var`, `@psalm-param` and `@psalm-return` ### `@psalm-var`, `@psalm-param` and `@psalm-return`
When specifying types in a format not supported phpDocumentor (but supported by Psalm) you may wish to prepend `@psalm-` to the PHPDoc tag, so as to avoid confusing your IDE. If a `@psalm`-prefixed tag is given, Psalm will use it in place of its non-prefixed counterpart. When specifying types in a format not supported phpDocumentor ([but supported by Psalm](#type-syntax)) you may wish to prepend `@psalm-` to the PHPDoc tag, so as to avoid confusing your IDE. If a `@psalm`-prefixed tag is given, Psalm will use it in place of its non-prefixed counterpart.
### `@psalm-suppress SomeIssueName` ### `@psalm-suppress SomeIssueName`
@ -80,8 +87,6 @@ function addString(?string $s) {
} }
``` ```
For example, we can suppress the possible
### `@psalm-ignore-nullable-return` ### `@psalm-ignore-nullable-return`
This can be used to tell Psalm not to worry if a function/method returns null. It’s a bit of a hack, but occasionally useful for scenarios where you either have a very high confidence of a non-null value, or some other function guarantees a non-null value for that particular code path. This can be used to tell Psalm not to worry if a function/method returns null. It’s a bit of a hack, but occasionally useful for scenarios where you either have a very high confidence of a non-null value, or some other function guarantees a non-null value for that particular code path.
@ -137,7 +142,7 @@ function array_combine(array $arr, array $arr2) {}
### `@psalm-seal-properties` ### `@psalm-seal-properties`
If you have a magic property getter/setter, you can use `@psalm-seal-properties` to instruct Psalm to disallow getting and setting any properties not contained in a list of `@property(-read|-write)` annotations. If you have a magic property getter/setter, you can use `@psalm-seal-properties` to instruct Psalm to disallow getting and setting any properties not contained in a list of `@property` (or `@property-read`/`@property-write`) annotations.
```php ```php
/** /**
@ -155,7 +160,7 @@ class A {
} }
$a = new A(); $a = new A();
$a->bar = 5; $a->bar = 5; // this call fails
``` ```
## Type Syntax ## Type Syntax
@ -196,7 +201,3 @@ function foo(array $arr): void {
foo(["cool", 4]); // passes foo(["cool", 4]); // passes
foo([4, "cool"]); // fails foo([4, "cool"]); // fails
``` ```