Update docs once more

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.

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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, ','); 
 }
 ```