Merge pull request #8754 from orklah/#8041

improve docs and phrasing about NoValue

docs/running_psalm/issues/NoValue.md

@@ -1,16 +1,41 @@
 # NoValue
 
-Emitted when using the result of a function that never returns.
+Emitted when Psalm invalidated all possible types for a given expression. It is often an indication that Psalm found dead code or that documented types were not exhaustive
 
 ```php
 <?php
 
 /**
- * @return never-returns
+ * @return never
  */
 function foo() : void {
     exit();
 }
 
-$a = foo();
+$a = foo(); // Psalm knows $a will never contain any type because foo() won't return
 ```
+
+```php
+<?php
+
+function foo() : void {
+    return throw new Exception(''); //Psalm detected the return expression is never used
+}
+```
+
+```php
+<?php
+function shutdown(): never {die('Application closed unexpectedly');}
+function foo(string $_a): void{}
+
+foo(shutdown()); // foo() will never be called
+```
+
+```php
+<?php
+$a = [];
+/** @psalm-suppress TypeDoesNotContainType */
+assert(!empty($a));
+
+count($a); // Assert above always fail. There is no possible type that $a can have here
+```

src/Psalm/Internal/Analyzer/Statements/Expression/AssignmentAnalyzer.php

@@ -530,7 +530,7 @@ public static function analyze(
             if ($context->vars_in_scope[$var_id]->isNever()) {
                 if (IssueBuffer::accepts(
                     new NoValue(
-                        'This function or method call never returns output',
+                        'All possible types for this assignment were invalidated - This may be dead code',
                         new CodeLocation($statements_analyzer->getSource(), $assign_var)
                     ),
                     $statements_analyzer->getSuppressedIssues()

src/Psalm/Internal/Analyzer/Statements/Expression/Call/ArgumentAnalyzer.php

@@ -810,7 +810,7 @@ public static function verifyType(
         if ($input_type->isNever()) {
             IssueBuffer::maybeAdd(
                 new NoValue(
-                    'This function or method call never returns output',
+                    'All possible types for this argument were invalidated - This may be dead code',
                     $arg_location
                 ),
                 $statements_analyzer->getSuppressedIssues()

src/Psalm/Internal/Analyzer/Statements/ReturnAnalyzer.php

@@ -177,7 +177,7 @@ public static function analyze(
                 if ($stmt_type->isNever()) {
                     IssueBuffer::maybeAdd(
                         new NoValue(
-                            'This function or method call never returns output',
+                            'All possible types for this return were invalidated - This may be dead code',
                             new CodeLocation($source, $stmt)
                         ),
                         $statements_analyzer->getSuppressedIssues()