Merge pull request #7593 from orklah/docproperties

doc about property initialization
vimeo · Feb 5, 2022 · 3a2b412 · 3a2b412
2 parents e00cbc7 + 8a41d61
commit 3a2b412
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 3 deletions.
diff --git a/docs/running_psalm/issues/MissingConstructor.md b/docs/running_psalm/issues/MissingConstructor.md
@@ -1,6 +1,16 @@
 # MissingConstructor
 
-Emitted when non-null properties without default values are defined in a class without a `__construct` method
+Unitialized properties are statically hard to analyze. To prevent mistakes, Psalm will enforce that all properties should be initialized.
+
+It does that through [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md) and this issue.
+
+Psalm will then assume every property in the codebase is initialized.
+
+Doing that allows it to report missing initializations as well as [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md)
+
+This issue is emitted when non-null properties without default values are defined in a class without a `__construct` method
+
+If your project rely on having uninitialized properties, it is advised to suppress this issue, as well as [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md) and [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md).
 
 ```php
 <?php

diff --git a/docs/running_psalm/issues/PropertyNotSetInConstructor.md b/docs/running_psalm/issues/PropertyNotSetInConstructor.md
@@ -1,6 +1,16 @@
 # PropertyNotSetInConstructor
 
-Emitted when a non-null property without a default value is declared but not set in the class’s constructor
+Unitialized properties are hard to statically analyze. To prevent mistakes, Psalm will enforce that all properties should be initialized.
+
+It does that through [MissingConstructor](issues/MissingConstructor.md) and this issue.
+
+Psalm will then assume every property in the codebase is initialized.
+
+Doing that allows it to report missing initializations as well as [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md)
+
+This issue is emitted when a non-null property without a default value is declared but not set in the class’s constructor
+
+If your project relies on having uninitialized properties, it is advised to suppress this issue, as well as [MissingConstructor](issues/MissingConstructor.md) and [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md).
 
 ```php
 <?php

diff --git a/docs/running_psalm/issues/RedundantPropertyInitializationCheck.md b/docs/running_psalm/issues/RedundantPropertyInitializationCheck.md
@@ -1,6 +1,16 @@
 # RedundantPropertyInitializationCheck
 
-Emitted when checking `isset()` on a non-nullable property. This issue indicate a redundant check for projects that initialize their properties in constructor.
+Unitialized properties are hard to statically analyze. To prevent mistakes, Psalm will enforce that all properties should be initialized.
+
+It does that through [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md) and [MissingConstructor](issues/MissingConstructor.md).
+
+Psalm will then assume every property in the codebase is initialized.
+
+Doing that allows it to report missing initializations as well as this issue.
+
+This issue is emitted when checking `isset()` on a non-nullable property. Because every property is assumed to be initialized, this check is redundant
+
+If your project relies on having uninitialized properties, it is advised to suppress this issue, as well as [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md) and [MissingConstructor](issues/MissingConstructor.md).
 
 ```php
 <?php