From 3f2615290da65d0b9993b921149f372492f333bf Mon Sep 17 00:00:00 2001
From: Matthew Brown <github@muglug.com>
Date: Sat, 21 Mar 2020 09:48:35 -0400
Subject: [PATCH] Update docs once more

---
 docs/running_psalm/issues/AbstractMethodCall.md             | 4 ++++
 docs/running_psalm/issues/AssignmentToVoid.md               | 6 +++++-
 docs/running_psalm/issues/CircularReference.md              | 4 ++++
 docs/running_psalm/issues/ConflictingReferenceConstraint.md | 4 ++++
 docs/running_psalm/issues/ContinueOutsideLoop.md            | 4 ++++
 docs/running_psalm/issues/DeprecatedClass.md                | 4 ++++
 docs/running_psalm/issues/DeprecatedConstant.md             | 4 ++++
 docs/running_psalm/issues/DeprecatedFunction.md             | 4 ++++
 docs/running_psalm/issues/DeprecatedInterface.md            | 4 ++++
 docs/running_psalm/issues/DeprecatedMethod.md               | 4 ++++
 docs/running_psalm/issues/DeprecatedProperty.md             | 4 ++++
 docs/running_psalm/issues/DeprecatedTrait.md                | 4 ++++
 docs/running_psalm/issues/DocblockTypeContradiction.md      | 4 ++++
 docs/running_psalm/issues/PossiblyFalseOperand.md           | 2 +-
 14 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/running_psalm/issues/AbstractMethodCall.md b/docs/running_psalm/issues/AbstractMethodCall.md
index b2dd14636..bc3faf54d 100644
--- a/docs/running_psalm/issues/AbstractMethodCall.md
+++ b/docs/running_psalm/issues/AbstractMethodCall.md
@@ -11,3 +11,7 @@ abstract class Base {
 
 Base::bar();
 ```
+
+## Why this is bad
+
+It's not allowed by PHP.
diff --git a/docs/running_psalm/issues/AssignmentToVoid.md b/docs/running_psalm/issues/AssignmentToVoid.md
index c793c7039..7076bbfd5 100644
--- a/docs/running_psalm/issues/AssignmentToVoid.md
+++ b/docs/running_psalm/issues/AssignmentToVoid.md
@@ -9,9 +9,13 @@ function foo() : void {}
 $a = foo();
 ```
 
+## Why this is bad
+
+Though `void`-returning functions are treated by PHP as returning `null` (so this on its own doesn’t lead to runtime errors), `void` is a concept more broadly in programming languages which is not designed for assignment purposes.
+
 ## How to fix
 
-You should just be able to remove the assignment:
+You should just be able to remove the assignment entirely:
 
 ```php
 <?php
diff --git a/docs/running_psalm/issues/CircularReference.md b/docs/running_psalm/issues/CircularReference.md
index cabf6c361..2882719af 100644
--- a/docs/running_psalm/issues/CircularReference.md
+++ b/docs/running_psalm/issues/CircularReference.md
@@ -8,3 +8,7 @@ Emitted when a class references itself as one of its parents
 class A extends B {}
 class B extends A {}
 ```
+
+## Why this is bad
+
+The code above will not compile
diff --git a/docs/running_psalm/issues/ConflictingReferenceConstraint.md b/docs/running_psalm/issues/ConflictingReferenceConstraint.md
index e4b3386c3..bac014cf4 100644
--- a/docs/running_psalm/issues/ConflictingReferenceConstraint.md
+++ b/docs/running_psalm/issues/ConflictingReferenceConstraint.md
@@ -33,3 +33,7 @@ if (rand(0, 1)) {
 
 $v = 8;
 ```
+
+## Why this is bad
+
+Psalm doesn't understand what the type of `$c` should be
diff --git a/docs/running_psalm/issues/ContinueOutsideLoop.md b/docs/running_psalm/issues/ContinueOutsideLoop.md
index 275e085af..3e31dea28 100644
--- a/docs/running_psalm/issues/ContinueOutsideLoop.md
+++ b/docs/running_psalm/issues/ContinueOutsideLoop.md
@@ -8,3 +8,7 @@ Emitted when encountering a `continue` statement outside a loop context.
 $a = 5;
 continue;
 ```
+
+## Why this is bad
+
+The code won't compile in PHP 5.6 and above.
diff --git a/docs/running_psalm/issues/DeprecatedClass.md b/docs/running_psalm/issues/DeprecatedClass.md
index 61f85e42c..4de6a3bc2 100644
--- a/docs/running_psalm/issues/DeprecatedClass.md
+++ b/docs/running_psalm/issues/DeprecatedClass.md
@@ -10,6 +10,10 @@ class A {}
 new A();
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated class.
diff --git a/docs/running_psalm/issues/DeprecatedConstant.md b/docs/running_psalm/issues/DeprecatedConstant.md
index 1806524cf..e8965dbb3 100644
--- a/docs/running_psalm/issues/DeprecatedConstant.md
+++ b/docs/running_psalm/issues/DeprecatedConstant.md
@@ -13,6 +13,10 @@ class A {
 echo A::FOO;
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated constant.
diff --git a/docs/running_psalm/issues/DeprecatedFunction.md b/docs/running_psalm/issues/DeprecatedFunction.md
index 8bc573938..245009a64 100644
--- a/docs/running_psalm/issues/DeprecatedFunction.md
+++ b/docs/running_psalm/issues/DeprecatedFunction.md
@@ -10,6 +10,10 @@ function foo() : void {}
 foo();
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated function.
diff --git a/docs/running_psalm/issues/DeprecatedInterface.md b/docs/running_psalm/issues/DeprecatedInterface.md
index 58279856a..d471dd56e 100644
--- a/docs/running_psalm/issues/DeprecatedInterface.md
+++ b/docs/running_psalm/issues/DeprecatedInterface.md
@@ -11,6 +11,10 @@ interface I {}
 class A implements I {}
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated interface.
diff --git a/docs/running_psalm/issues/DeprecatedMethod.md b/docs/running_psalm/issues/DeprecatedMethod.md
index 0b11b54e5..f3380373a 100644
--- a/docs/running_psalm/issues/DeprecatedMethod.md
+++ b/docs/running_psalm/issues/DeprecatedMethod.md
@@ -12,6 +12,10 @@ class A {
 (new A())->foo();
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated method.
diff --git a/docs/running_psalm/issues/DeprecatedProperty.md b/docs/running_psalm/issues/DeprecatedProperty.md
index 55897a364..c7a112032 100644
--- a/docs/running_psalm/issues/DeprecatedProperty.md
+++ b/docs/running_psalm/issues/DeprecatedProperty.md
@@ -15,6 +15,10 @@ class A {
 (new A())->foo = 5;
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated property.
diff --git a/docs/running_psalm/issues/DeprecatedTrait.md b/docs/running_psalm/issues/DeprecatedTrait.md
index aa29a8585..251b91cea 100644
--- a/docs/running_psalm/issues/DeprecatedTrait.md
+++ b/docs/running_psalm/issues/DeprecatedTrait.md
@@ -12,6 +12,10 @@ class A {
 }
 ```
 
+## Why this is bad
+
+The `@deprecated` tag is normally indicative of code that will stop working in the near future.
+
 ## How to fix
 
 Don’t use the deprecated trait.
diff --git a/docs/running_psalm/issues/DocblockTypeContradiction.md b/docs/running_psalm/issues/DocblockTypeContradiction.md
index f8f1c8819..136171ec5 100644
--- a/docs/running_psalm/issues/DocblockTypeContradiction.md
+++ b/docs/running_psalm/issues/DocblockTypeContradiction.md
@@ -19,6 +19,10 @@ function foo($s) {
 }
 ```
 
+## Why this is bad
+
+This can sometimes point to a flaw in either your docblock types, or some unnecessary runtime checks in an environment where all types can be checked by Psalm, without the need for additional runtime checks.
+
 ## How to fix
 
 A lot of old PHP code is set up to prevent unexpected errors with checks like the one above.
diff --git a/docs/running_psalm/issues/PossiblyFalseOperand.md b/docs/running_psalm/issues/PossiblyFalseOperand.md
index 08826bfc6..56ba59d7d 100644
--- a/docs/running_psalm/issues/PossiblyFalseOperand.md
+++ b/docs/running_psalm/issues/PossiblyFalseOperand.md
@@ -6,7 +6,7 @@ Emitted when using a possibly `false` value as part of an operation (e.g. `+`, `
 <?php
 
 function echoCommaPosition(string $str) : void {
-    echo 'The comma is located at ' . false; 
+    echo 'The comma is located at ' . strpos($str, ','); 
 }
 ```