From 0d3f5af18c2013bc1c3999d276253a7f7e823516 Mon Sep 17 00:00:00 2001 From: Brown Date: Thu, 27 Jun 2019 17:00:26 -0400 Subject: [PATCH] Break out docblock_type_syntax.md into separate files --- docs/README.md | 8 +- docs/annotating_code/docblock_type_syntax.md | 88 +------------------ .../type_syntax/atomic_types.md | 56 ++++++++++++ .../type_syntax/intersection_types.md | 12 +++ .../type_syntax/union_types.md | 15 ++++ 5 files changed, 85 insertions(+), 94 deletions(-) create mode 100644 docs/annotating_code/type_syntax/atomic_types.md create mode 100644 docs/annotating_code/type_syntax/intersection_types.md create mode 100644 docs/annotating_code/type_syntax/union_types.md diff --git a/docs/README.md b/docs/README.md index 17f16bd69..68c730ed1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -65,13 +65,7 @@ There are two main inspirations for Psalm: - [Docblock Type Syntax](annotating_code/docblock_type_syntax.md) - [Supported Annotations](annotating_code/supported_annotations.md) - [Template Annotations](annotating_code/templated_annotations.md) - - Type syntax: - - [Array types](annotating_code/type_syntax/array_types.md) - - [Callable types](annotating_code/type_syntax/callable_types.md) - - [Object types](annotating_code/type_syntax/object_types.md) - - [Scalar types](annotating_code/type_syntax/scalar_types.md) - - [Value types](annotating_code/type_syntax/value_types.md) - Manipulating code: - [Fixing code](manipulating_code/fixing.md) - [Refactoring code](manipulating_code/refactoring.md) - + diff --git a/docs/annotating_code/docblock_type_syntax.md b/docs/annotating_code/docblock_type_syntax.md index 2ad908ebd..fdf57899e 100644 --- a/docs/annotating_code/docblock_type_syntax.md +++ b/docs/annotating_code/docblock_type_syntax.md @@ -1,91 +1,5 @@ # Docblock Type Syntax -## Atomic types - -Atomic types are the basic building block of all type information used in Psalm. Multiple atomic types can be combined, either with [union types](#union-types) or [intersection types](#intersection_types). Psalm allows many different sorts of atomic types to be expressed in docblock syntax: - -### [Scalar types](type_syntax/scalar_types.md) - -- [`int`](type_syntax/scalar_types.md) -- [`float`](type_syntax/scalar_types.md) -- [`string`](type_syntax/scalar_types.md) -- [`class-string` and `class-string`](type_syntax/scalar_types.md#class-string) -- [`trait-string`](type_syntax/scalar_types.md#trait-string) -- [`callable-string`](type_syntax/scalar_types.md#callable-string) -- [`numeric-string`](type_syntax/scalar_types.md#numeric-string) -- [`bool`](type_syntax/scalar_types.md) -- [`array-key`](type_syntax/scalar_types.md#array-key) -- [`numeric`](type_syntax/scalar_types.md#numeric) -- [`scalar`](type_syntax/scalar_types.md#scalar) - -### [Object types](type_syntax/object_types.md) - -- [`object`](type_syntax/object_types.md) -- [`Exception`, `Foo\MyClass` and `Foo\MyClass`](type_syntax/object_types.md) - -### [Array types](type_syntax/array_types.md) - -- [`array` & `non-empty-array`](type_syntax/array_types.md) -- [`string[]`](type_syntax/array_types.md#phpdoc-syntax) -- [`array`](type_syntax/array_types.md#generic-arrays) -- [`array{foo: int, bar: string}`](type_syntax/array_types.md#object-like-arrays) - -### [Callable types](type_syntax/callable_types.md) - -- [`callable`, `Closure` and `callable(Foo, Bar):Baz`](type_syntax/callable_types.md) - -### [Value types](type_syntax/value_types.md) - -- [`null`](type_syntax/value_types.md#null) -- [`true`, `false`](type_syntax/value_types.md#true-false) -- [`6`, `7.0`, `"fourty-two"` and `'fourty two'`](type_syntax/value_types.md#some_string-4-314) -- [`Foo\Bar::MY_SCALAR_CONST`](type_syntax/value_types.md#regular-class-constants) - -### Magical types - -- `key-of` -- `value-of` -- `T[K]` - -### Other - -- `iterable` - represents the [`iterable` pseudo-type](https://php.net/manual/en/language.types.iterable.php). Like arrays, iterables can have type parameters e.g. `iterable`. -- `void` - can be used in a return type when a function does not return a value. -- `empty` - a type that represents a lack of type - not just a lack of type information (that's where [mixed](#mixed) is useful) but where there can be no type. A good example is the type of the empty array `[]`. Psalm types this as `array`. -- `mixed` represents a lack of type information. Psalm warns about mixed when the `totallyTyped` flag is turned on. -- `resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php). -- `no-return` is the 'return type' for a function that can never actually return, such as `die()`, `exit()`, or a function that -always throws an exception. It may also be written as `never-return` or `never-returns`, and is also known as the *bottom type*. - -## Union Types - -An annotation of the form `Type1|Type2|Type3` is a _Union Type_. `Type1`, `Type2` and `Type3` are all acceptable possible types of that union type. - -`Type1`, `Type2` and `Type3` are each [atomic types](#atomic-types). - -Union types can be generated in a number of different ways, for example in ternary expressions: - -```php -$rabbit = rand(0, 10) === 4 ? 'rabbit' : ['rabbit']; -``` - -`$rabbit` will be either a `string` or an `array`. We can represent that idea with Union Types – so `$rabbit` is typed as `string|array`. Union types represent *all* the possible types a given variable can have. - -PHP builtin functions also have union-type returns - `strpos` can return `false` in some situations, `int` in others. We represent that union type with `int|false`. - -## Intersection types - -An annotation of the form `Type1&Type2&Type3` is an _Intersection Type_. Any value must satisfy `Type1`, `Type2` and `Type3` simultaneously. `Type1`, `Type2` and `Type3` are all [atomic types](#atomic_types). - -For example, after this statement in a PHPUnit test: -```php - -$hare = $this->createMock(Hare::class); -``` -`$hare` will be an instance of a class that extends `Hare`, and implements `\PHPUnit\Framework\MockObject\MockObject`. So -`$hare` is typed as `Hare&\PHPUnit\Framework\MockObject\MockObject`. You can use this syntax whenever a value is -required to implement multiple interfaces. Only *object types* may be used within an intersection. - -## Backwards compatibility +All docblock types are either [atomic types](atomic_types.md), [union types](union_types.md) or [intersection types](intersection_types.md). Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/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/docs/annotating_code/type_syntax/atomic_types.md b/docs/annotating_code/type_syntax/atomic_types.md new file mode 100644 index 000000000..a3e55ff3e --- /dev/null +++ b/docs/annotating_code/type_syntax/atomic_types.md @@ -0,0 +1,56 @@ +# Atomic types + +Atomic types are the basic building block of all type information used in Psalm. Multiple atomic types can be combined, either with [union types](#union-types) or [intersection types](#intersection_types). Psalm allows many different sorts of atomic types to be expressed in docblock syntax: + +## [Scalar types](scalar_types.md) + +- [`int`](scalar_types.md) +- [`float`](scalar_types.md) +- [`string`](scalar_types.md) +- [`class-string` and `class-string`](scalar_types.md#class-string) +- [`trait-string`](scalar_types.md#trait-string) +- [`callable-string`](scalar_types.md#callable-string) +- [`numeric-string`](scalar_types.md#numeric-string) +- [`bool`](scalar_types.md) +- [`array-key`](scalar_types.md#array-key) +- [`numeric`](scalar_types.md#numeric) +- [`scalar`](scalar_types.md#scalar) + +## [Object types](object_types.md) + +- [`object`](object_types.md) +- [`Exception`, `Foo\MyClass` and `Foo\MyClass`](object_types.md) + +## [Array types](array_types.md) + +- [`array` & `non-empty-array`](array_types.md) +- [`string[]`](array_types.md#phpdoc-syntax) +- [`array`](array_types.md#generic-arrays) +- [`array{foo: int, bar: string}`](array_types.md#object-like-arrays) + +## [Callable types](callable_types.md) + +- [`callable`, `Closure` and `callable(Foo, Bar):Baz`](callable_types.md) + +## [Value types](value_types.md) + +- [`null`](value_types.md#null) +- [`true`, `false`](value_types.md#true-false) +- [`6`, `7.0`, `"fourty-two"` and `'fourty two'`](value_types.md#some_string-4-314) +- [`Foo\Bar::MY_SCALAR_CONST`](value_types.md#regular-class-constants) + +## Magical types + +- `key-of` +- `value-of` +- `T[K]` + +## Other + +- `iterable` - represents the [`iterable` pseudo-type](https://php.net/manual/en/language.types.iterable.php). Like arrays, iterables can have type parameters e.g. `iterable`. +- `void` - can be used in a return type when a function does not return a value. +- `empty` - a type that represents a lack of type - not just a lack of type information (that's where [mixed](#mixed) is useful) but where there can be no type. A good example is the type of the empty array `[]`. Psalm types this as `array`. +- `mixed` represents a lack of type information. Psalm warns about mixed when the `totallyTyped` flag is turned on. +- `resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php). +- `no-return` is the 'return type' for a function that can never actually return, such as `die()`, `exit()`, or a function that +always throws an exception. It may also be written as `never-return` or `never-returns`, and is also known as the *bottom type*. diff --git a/docs/annotating_code/type_syntax/intersection_types.md b/docs/annotating_code/type_syntax/intersection_types.md new file mode 100644 index 000000000..6c6c98211 --- /dev/null +++ b/docs/annotating_code/type_syntax/intersection_types.md @@ -0,0 +1,12 @@ +# Intersection types + +An annotation of the form `Type1&Type2&Type3` is an _Intersection Type_. Any value must satisfy `Type1`, `Type2` and `Type3` simultaneously. `Type1`, `Type2` and `Type3` are all [atomic types](atomic_types.md). + +For example, after this statement in a PHPUnit test: +```php + +$hare = $this->createMock(Hare::class); +``` +`$hare` will be an instance of a class that extends `Hare`, and implements `\PHPUnit\Framework\MockObject\MockObject`. So +`$hare` is typed as `Hare&\PHPUnit\Framework\MockObject\MockObject`. You can use this syntax whenever a value is +required to implement multiple interfaces. Only *object types* may be used within an intersection. diff --git a/docs/annotating_code/type_syntax/union_types.md b/docs/annotating_code/type_syntax/union_types.md new file mode 100644 index 000000000..5185eec16 --- /dev/null +++ b/docs/annotating_code/type_syntax/union_types.md @@ -0,0 +1,15 @@ +# Union Types + +An annotation of the form `Type1|Type2|Type3` is a _Union Type_. `Type1`, `Type2` and `Type3` are all acceptable possible types of that union type. + +`Type1`, `Type2` and `Type3` are each [atomic types](atomic_types.md). + +Union types can be generated in a number of different ways, for example in ternary expressions: + +```php +$rabbit = rand(0, 10) === 4 ? 'rabbit' : ['rabbit']; +``` + +`$rabbit` will be either a `string` or an `array`. We can represent that idea with Union Types – so `$rabbit` is typed as `string|array`. Union types represent *all* the possible types a given variable can have. + +PHP builtin functions also have union-type returns - `strpos` can return `false` in some situations, `int` in others. We represent that union type with `int|false`.