improve Atomic Types documentation (#4735)

* improve Atomic Types documentation

* add doc

* add doc

docs/running_psalm/plugins/plugins_type_system.md

@@ -17,7 +17,7 @@ new Union([new TString(), new TInt()]); // equivalent to string|int in docblock
 
 Primitive types like floats, integers and strings, plus arrays, and classes. You can find all of these in [`src/Psalm/Types/Atomic`](https://github.com/vimeo/psalm/tree/master/src/Psalm/Type/Atomic).
 
-Note that all non-abstract classes in this folder are valid types. Most (with the exception of `Fn`, `TKeyedArray`, `GetClassT` and `GetTypeT`) are prefixed 'T'.
+Note that all non-abstract classes in this folder are valid types. They are all prefixed by 'T'.
 
 The classes are as follows:
 
@@ -41,16 +41,40 @@ The classes are as follows:
 
 `TResource` - denotes the `resource` type (e.g. a file handle).
 
+`TClosedResource` - denotes the `resource` type that has been closed (e.g. a file handle through `fclose()`).
+
+`TAssertionFalsy` - Represents any value reduced to false when computed in boolean context. This is used for assertions
+
+`TConditional` - Internal representation of a conditional return type in phpdoc. For example ($param1 is int ? int : string)
+
+`TIntMask` - Represents the type that is the result of a bitmask combination of its parameters. `int-mask<1, 2, 4>` corresponds to `1|2|3|4|5|6|7`
+
+`TIntMaskOf` - as above, but used with with a reference to constants in code`int-mask<MyClass::CLASS_CONSTANT_*>` will corresponds to `1|2|3|4|5|6|7` if there are three constant 1, 2 and 4
+
+`TKeyOfClassConstant` - Represents an offset of a class constant array.
+
+`TValueOfClassConstant` - Represents a value of a class constant array.
+
+`TTemplateIndexedAccess` - To be documented
+
+`TTemplateKeyOf` - Represents the type used when using TKeyOfClassConstant when the type of the class constant array is a template
+
+`TTypeAlias` - To be documented
+
 ### Scalar supertype
 
 `TScalar` - denotes the `scalar` super type (which can also result from an `is_scalar` check). This type encompasses `float`, `int`, `bool` and `string`.
 
 `TEmptyScalar` - denotes a `scalar` type that is also empty.
 
+`TNonEmptyScalar` - denotes a `scalar` type that is also non-empty.
+
 ### Numeric supertype
 
 `TNumeric` - denotes the `numeric` type (which can also result from an `is_numeric` check).
 
+`TEmptyNumeric` - denotes the `numeric` type that's also empty (which can also result from an `is_numeric` and `empty` check).
+
 ### Scalar types
 
 All scalar types have literal versions e.g. `int` vs `int(5)`.
@@ -59,13 +83,15 @@ All scalar types have literal versions e.g. `int` vs `int(5)`.
 
 `TInt` - denotes the `int` type, where the exact value is unknown.
 
-`TLiteralInt` is used to represent an integer value where the exact numeric value is known.
+`TLiteralInt` - is used to represent an integer value where the exact numeric value is known.
+
+`TPositiveInt` - denotes an int that is also positive (strictly > 0)
 
 #### Floats
 
 `TFloat` - denotes the `float` type, where the exact value is unknown.
 
-`TLiteralFloat` is used to represent a floating point value where the exact numeric value is known.
+`TLiteralFloat` - is used to represent a floating point value where the exact numeric value is known.
 
 #### Bools
 
@@ -95,18 +121,34 @@ if (true === $first) {
 
 `TString` - denotes the `string` type, where the exact value is unknown.
 
+`TNonEmptyString` - denotes a string, that is also non-empty
+
 `TNumericString` - denotes a string that's also a numeric value e.g. `"5"`. It can result from `is_string($s) && is_numeric($s)`.
 
-`TLiteralString` is used to represent a string whose value is known.
+`TLiteralString` - is used to represent a string whose value is known.
 
 `TClassString` - denotes the `class-string` type, used to describe a string representing a valid PHP class. The parent type from which the classes descend may or may not be specified in the constructor.
 
 `TLiteralClassString` - denotes a specific class string, generated by expressions like `A::class`.
 
+`TTraitString` - denotes the `trait-string` type, used to describe a string representing a valid PHP trait.
+
+`TDependentGetClass` - Represents a string whose value is a fully-qualified class found by get_class($var)
+
+`TDependentGetDebugType` - Represents a string whose value is that of a type found by get_debug_type($var)
+
+`TDependentGetType` - Represents a string whose value is that of a type found by gettype($var)
+
 `TCallableString` - denotes the `callable-string` type, used to represent an unknown string that is also `callable`.
 
 `THtmlEscapedString`, `TSqlSelectString` - these are special types, specifically for consumption by plugins.
 
+`TLowercaseString` - denotes a string where every character is lowercased. (which can also result from a `strtolower` call).
+
+`TNonEmptyLowercaseString` - denotes a non-empty-string where every character is lowercased. (which can also result from a `strtolower` call).
+
+`TSingleLetter` - denotes a string that has a length of 1
+
 #### Scalar class constants
 
 `TScalarClassConstant` - denotes a class constant whose value might not yet be known.
@@ -119,6 +161,8 @@ if (true === $first) {
 
 `TArray` - denotes a simple array of the form `array<TKey, TValue>`. It expects an array with two elements, both union types.
 
+`TList` - Represents an array that has some particularities: its keys are integers, they start at 0, they are consecutive and go upwards (no negative int)
+
 `TNonEmptyArray` - as above, but denotes an array known to be non-empty.
 
 `TKeyedArray` represents an 'object-like array' - an array with known keys.
@@ -137,14 +181,18 @@ foreach (range(1,1) as $_) $a[(string)rand(0,1)] = rand(0,1); // array<string,in
 
 `TCallableArray` - denotes an array that is _also_ `callable`.
 
+`TCallableList` - denotes a list that is _also_ `callable`.
+
 `TCallableKeyedArray` - denotes an object-like array that is _also_ `callable`.
 
+`TClassStringMap` - Represents an array where the type of each value is a function of its string key value
+
 ### Callables & closures
 
 `TCallable` - denotes the `callable` type. Can result from an `is_callable` check.
-`Fn` - denotes a `Closure` type.
+`TClosure` - denotes a `Closure` type.
 
-`TCallable` and `Fn` can optionally be defined with parameters and return types, too
+`TCallable` and `TClosure` can optionally be defined with parameters and return types, too
 
 ### Object supertypes
 
@@ -160,6 +208,8 @@ foreach (range(1,1) as $_) $a[(string)rand(0,1)] = rand(0,1); // array<string,in
 
 `TCallableObject` - denotes an object that is also `callable` (i.e. it has `__invoke` defined).
 
+`TAnonymousClassInstance` - Denotes an anonymous class (i.e. `new class{}`) with potential methods
+
 ### Template
 
 `TTemplateParam` - denotes a template parameter that has been previously specified in a `@template` tag.

src/Psalm/Type/Atomic/TAnonymousClassInstance.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes an anonymous class (i.e. `new class{}`) with potential methods
+ */
 class TAnonymousClassInstance extends TNamedObject
 {
     public function toPhpString(

src/Psalm/Type/Atomic/TArray.php

@@ -6,7 +6,7 @@ use function get_class;
 use Psalm\Type\Atomic;
 
 /**
- * Represents an array with generic type parameters.
+ * Denotes a simple array of the form `array<TKey, TValue>`. It expects an array with two elements, both union types.
  */
 class TArray extends \Psalm\Type\Atomic
 {

src/Psalm/Type/Atomic/TArrayKey.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `array-key` type, used for something that could be the offset of an `array`.
+ */
 class TArrayKey extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TAssertionFalsy.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Represents any value reduced to false when computed in boolean context. This is used for assertions
+ */
 class TAssertionFalsy extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TBool.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `bool` type where the exact value is unknown.
+ */
 class TBool extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TCallable.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `callable` type. Can result from an `is_callable` check.
+ */
 class TCallable extends \Psalm\Type\Atomic
 {
     use CallableTrait;

src/Psalm/Type/Atomic/TCallableArray.php

@@ -2,7 +2,7 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Denotes an array that is _also_ `callable`.
  */
 class TCallableArray extends TNonEmptyArray
 {

src/Psalm/Type/Atomic/TCallableKeyedArray.php

@@ -2,7 +2,7 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Denotes an object-like array that is _also_ `callable`.
  */
 class TCallableKeyedArray extends TKeyedArray
 {

src/Psalm/Type/Atomic/TCallableList.php

@@ -2,7 +2,7 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Denotes a list that is _also_ `callable`.
  */
 class TCallableList extends TNonEmptyList
 {

src/Psalm/Type/Atomic/TCallableObject.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes an object that is also `callable` (i.e. it has `__invoke` defined).
+ */
 class TCallableObject extends TObject
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TCallableString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `callable-string` type, used to represent an unknown string that is also `callable`.
+ */
 class TCallableString extends TString
 {
 

src/Psalm/Type/Atomic/TClassString.php

@@ -12,6 +12,10 @@ use function stripos;
 use function strpos;
 use function strtolower;
 
+/**
+ * Denotes the `class-string` type, used to describe a string representing a valid PHP class.
+ * The parent type from which the classes descend may or may not be specified in the constructor.
+ */
 class TClassString extends TString
 {
     /**

src/Psalm/Type/Atomic/TClosedResource.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `resource` type that has been closed (e.g. a file handle through `fclose()`).
+ */
 class TClosedResource extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TConditional.php

@@ -6,6 +6,9 @@ use Psalm\Internal\Type\TemplateResult;
 use Psalm\Internal\Type\TemplateInferredTypeReplacer;
 use Psalm\Type\Union;
 
+/**
+ * Internal representation of a conditional return type in phpdoc. For example ($param1 is int ? int : string)
+ */
 class TConditional extends \Psalm\Type\Atomic
 {
     /**

src/Psalm/Type/Atomic/TEmpty.php

@@ -1,6 +1,10 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `empty` type, used to describe a type corresponding to no value whatsoever.
+ * Empty arrays `[]` have the type `array<empty, empty>`.
+ */
 class TEmpty extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TEmptyMixed.php

@@ -1,6 +1,10 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `mixed` type, but empty.
+ * Generated for `$x` inside the `if` statement `if (!$x) {...}` when `$x` is `mixed` outside.
+ */
 class TEmptyMixed extends TMixed
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TEmptyNumeric.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `numeric` type that's also empty (which can also result from an `is_numeric` and `empty` check).
+ */
 class TEmptyNumeric extends TNumeric
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TEmptyScalar.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a `scalar` type that is also empty.
+ */
 class TEmptyScalar extends TScalar
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TFalse.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `false` value type
+ */
 class TFalse extends TBool
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TFloat.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `float` type, where the exact value is unknown.
+ */
 class TFloat extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TGenericObject.php

@@ -7,6 +7,9 @@ use Psalm\Type\Atomic;
 use function substr;
 use function array_merge;
 
+/**
+ * Denotes an object type that has generic parameters e.g. `ArrayObject<string, Foo\Bar>`
+ */
 class TGenericObject extends TNamedObject
 {
     use GenericTrait;

src/Psalm/Type/Atomic/THtmlEscapedString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Special type, specifically for consumption by plugins.
+ */
 class THtmlEscapedString extends TString
 {
     public function getKey(bool $include_extra = true): string

src/Psalm/Type/Atomic/TInt.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `int` type, where the exact value is unknown.
+ */
 class TInt extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TIntMask.php

@@ -3,6 +3,10 @@ namespace Psalm\Type\Atomic;
 
 use function substr;
 
+/**
+ * Represents the type that is the result of a bitmask combination of its parameters.
+ * `int-mask<1, 2, 4>` corresponds to `1|2|3|4|5|6|7`
+ */
 class TIntMask extends TInt
 {
     /** @var non-empty-array<TLiteralInt|TScalarClassConstant> */

src/Psalm/Type/Atomic/TIntMaskOf.php

@@ -1,6 +1,11 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Represents the type that is the result of a bitmask combination of its parameters.
+ * This is the same concept as TIntMask but TIntMaskOf is used with with a reference to constants in code
+ * `int-mask<MyClass::CLASS_CONSTANT_*>` will corresponds to `1|2|3|4|5|6|7` if there are three constant 1, 2 and 4
+ */
 class TIntMaskOf extends TInt
 {
     /** @var TScalarClassConstant|TKeyOfClassConstant|TValueOfClassConstant */

src/Psalm/Type/Atomic/TIterable.php

@@ -7,6 +7,9 @@ use Psalm\Type\Atomic;
 use function substr;
 use function array_merge;
 
+/**
+ * denotes the `iterable` type(which can also result from an `is_iterable` check).
+ */
 class TIterable extends Atomic
 {
     use HasIntersectionTrait;

src/Psalm/Type/Atomic/TKeyOfClassConstant.php

@@ -7,6 +7,9 @@ use function stripos;
 use function strpos;
 use function strtolower;
 
+/**
+ * Represents an offset of a class constant array.
+ */
 class TKeyOfClassConstant extends Scalar
 {
     /** @var string */

src/Psalm/Type/Atomic/TKeyedArray.php

@@ -19,7 +19,7 @@ use Psalm\Type\Atomic;
 use Psalm\Type\Union;
 
 /**
- * Represents an array where we know its key values
+ * Represents an 'object-like array' - an array with known keys.
  */
 class TKeyedArray extends \Psalm\Type\Atomic
 {

src/Psalm/Type/Atomic/TList.php

@@ -12,7 +12,10 @@ use Psalm\Type\Atomic;
 use Psalm\Type\Union;
 
 /**
- * Represents an array where we know its key values
+ * Represents an array that has some particularities:
+ * - its keys are integers
+ * - they start at 0
+ * - they are consecutive and go upwards (no negative int)
  */
 class TList extends \Psalm\Type\Atomic
 {

src/Psalm/Type/Atomic/TLiteralClassString.php

@@ -7,6 +7,9 @@ use function stripos;
 use function strpos;
 use function strtolower;
 
+/**
+ * Denotes a specific class string, generated by expressions like `A::class`.
+ */
 class TLiteralClassString extends TLiteralString
 {
     /**

src/Psalm/Type/Atomic/TLiteralFloat.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a floating point value where the exact numeric value is known.
+ */
 class TLiteralFloat extends TFloat
 {
     /** @var float */

src/Psalm/Type/Atomic/TLiteralInt.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes an integer value where the exact numeric value is known.
+ */
 class TLiteralInt extends TInt
 {
     /** @var int */

src/Psalm/Type/Atomic/TLiteralString.php

@@ -5,6 +5,9 @@ use function preg_replace;
 use function strlen;
 use function substr;
 
+/**
+ * Denotes a string whose value is known.
+ */
 class TLiteralString extends TString
 {
     /** @var string */

src/Psalm/Type/Atomic/TMixed.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `mixed` type, used when you don’t know the type of an expression.
+ */
 class TMixed extends \Psalm\Type\Atomic
 {
     /** @var bool */

src/Psalm/Type/Atomic/TNamedObject.php

@@ -9,6 +9,9 @@ use Psalm\Type\Atomic;
 use function substr;
 use function array_map;
 
+/**
+ * Denotes an object type where the type of the object is known e.g. `Exception`, `Throwable`, `Foo\Bar`
+ */
 class TNamedObject extends Atomic
 {
     use HasIntersectionTrait;

src/Psalm/Type/Atomic/TNever.php

@@ -1,6 +1,10 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `no-return`/`never-return` type for functions that never return, either throwing an exception or
+ * terminating (like the builtin `exit()`).
+ */
 class TNever extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TNonEmptyArray.php

@@ -2,7 +2,8 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Denotes array known to be non-empty of the form `non-empty-array<TKey, TValue>`.
+ * It expects an array with two elements, both union types.
  */
 class TNonEmptyArray extends TArray
 {

src/Psalm/Type/Atomic/TNonEmptyList.php

@@ -2,7 +2,7 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Represents a non-empty list
  */
 class TNonEmptyList extends TList
 {

src/Psalm/Type/Atomic/TNonEmptyLowercaseString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a non-empty-string where every character is lowercased. (which can also result from a `strtolower` call).
+ */
 class TNonEmptyLowercaseString extends TNonEmptyString
 {
     public function getKey(bool $include_extra = true): string

src/Psalm/Type/Atomic/TNonEmptyMixed.php

@@ -1,6 +1,10 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `mixed` type, but not empty.
+ * Generated for `$x` inside the `if` statement `if ($x) {...}` when `$x` is `mixed` outside.
+ */
 class TNonEmptyMixed extends TMixed
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TNonEmptyScalar.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a `scalar` type that is also non-empty.
+ */
 class TNonEmptyScalar extends TScalar
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TNonEmptyString.php

@@ -2,7 +2,7 @@
 namespace Psalm\Type\Atomic;
 
 /**
- * Represents a non-empty array
+ * Denotes a string, that is also non-empty
  */
 class TNonEmptyString extends TString
 {

src/Psalm/Type/Atomic/TNull.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `null` type
+ */
 class TNull extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TNumeric.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `numeric` type (which can also result from an `is_numeric` check).
+ */
 class TNumeric extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TNumericString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a string that's also a numeric value e.g. `"5"`. It can result from `is_string($s) && is_numeric($s)`.
+ */
 class TNumericString extends TString
 {
     public function getKey(bool $include_extra = true): string

src/Psalm/Type/Atomic/TObject.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `object` type
+ */
 class TObject extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TObjectWithProperties.php

@@ -15,6 +15,9 @@ use Psalm\Internal\Type\TemplateInferredTypeReplacer;
 use function array_merge;
 use function array_values;
 
+/**
+ * Denotes an object with specified member variables e.g. `object{foo:int, bar:string}`.
+ */
 class TObjectWithProperties extends TObject
 {
     use HasIntersectionTrait;

src/Psalm/Type/Atomic/TPositiveInt.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes an int that is also positive (strictly > 0)
+ */
 class TPositiveInt extends TInt
 {
     public function getId(bool $nested = false): string

src/Psalm/Type/Atomic/TResource.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `resource` type (e.g. a file handle).
+ */
 class TResource extends \Psalm\Type\Atomic
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TScalar.php

@@ -1,6 +1,10 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `scalar` super type (which can also result from an `is_scalar` check).
+ * This type encompasses `float`, `int`, `bool` and `string`.
+ */
 class TScalar extends Scalar
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TScalarClassConstant.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a class constant whose value might not yet be known.
+ */
 class TScalarClassConstant extends Scalar
 {
     /** @var string */

src/Psalm/Type/Atomic/TSingleLetter.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a string that has a length of 1
+ */
 class TSingleLetter extends TString
 {
 }

src/Psalm/Type/Atomic/TString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `string` type, where the exact value is unknown.
+ */
 class TString extends Scalar
 {
     /**

src/Psalm/Type/Atomic/TTemplateKeyOf.php

@@ -3,6 +3,9 @@ namespace Psalm\Type\Atomic;
 
 use Psalm\Type\Union;
 
+/**
+ * Represents the type used when using TKeyOfClassConstant when the type of the class constant array is a template
+ */
 class TTemplateKeyOf extends TArrayKey
 {
     /**

src/Psalm/Type/Atomic/TTemplateParam.php

@@ -7,6 +7,9 @@ use Psalm\Internal\Type\TemplateResult;
 use Psalm\Type\Union;
 use function array_map;
 
+/**
+ * denotes a template parameter that has been previously specified in a `@template` tag.
+ */
 class TTemplateParam extends \Psalm\Type\Atomic
 {
     use HasIntersectionTrait;

src/Psalm/Type/Atomic/TTemplateParamClass.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes a `class-string` corresponding to a template parameter previously specified in a `@template` tag.
+ */
 class TTemplateParamClass extends TClassString
 {
     /**

src/Psalm/Type/Atomic/TTraitString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `trait-string` type, used to describe a string representing a valid PHP trait.
+ */
 class TTraitString extends TString
 {
     public function getKey(bool $include_extra = true): string

src/Psalm/Type/Atomic/TTrue.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `true` value type
+ */
 class TTrue extends TBool
 {
     public function __toString(): string

src/Psalm/Type/Atomic/TValueOfClassConstant.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Represents a value of a class constant array.
+ */
 class TValueOfClassConstant extends \Psalm\Type\Atomic
 {
     /** @var string */

src/Psalm/Type/Atomic/TVoid.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Type\Atomic;
 
+/**
+ * Denotes the `void` type, normally just used to annotate a function/method that returns nothing
+ */
 class TVoid extends \Psalm\Type\Atomic
 {
     public function __toString(): string

tests/Config/Plugin/Hook/StringProvider/TSqlSelectString.php

@@ -1,6 +1,9 @@
 <?php
 namespace Psalm\Test\Config\Plugin\Hook\StringProvider;
 
+/**
+ * Special type, specifically for consumption by plugins.
+ */
 class TSqlSelectString extends \Psalm\Type\Atomic\TLiteralString
 {
     public function getKey(bool $include_extra = true) : string