add annotation @psalm-param-out (#4717)

* add annotation @psalm-param-out

* add tag in documentation

docs/annotating_code/supported_annotations.md

@@ -51,7 +51,7 @@ function bat(): string {
 
 There are a number of custom tags that determine how Psalm treats your code.
 
-### `@param-out`
+### `@param-out`, `@psalm-param-out`
 
 This is used to specify that a by-ref type is different from the one that entered. In the function below the first param can be null, but once the function has executed the by-ref value is not null.
 

src/Psalm/DocComment.php

@@ -35,8 +35,8 @@ class DocComment
         'allow-private-mutation', 'readonly-allow-private-mutation',
         'yield', 'trace', 'import-type', 'flow', 'taint-specialize', 'taint-escape',
         'taint-unescape', 'self-out', 'consistent-constructor', 'stub-override',
-        'require-extends', 'require-implements',
-        'if-this-is'
+        'if-this-is',
+        'require-extends', 'require-implements', 'param-out'
     ];
 
     /**

src/Psalm/Internal/PhpVisitor/Reflector/FunctionLikeDocblockParser.php

@@ -91,8 +91,8 @@ class FunctionLikeDocblockParser
             }
         }
 
-        if (isset($parsed_docblock->tags['param-out'])) {
-            foreach ($parsed_docblock->tags['param-out'] as $offset => $param) {
+        if (isset($parsed_docblock->combined_tags['param-out'])) {
+            foreach ($parsed_docblock->combined_tags['param-out'] as $offset => $param) {
                 $line_parts = CommentAnalyzer::splitDocLine($param);
 
                 if (count($line_parts) === 1 && isset($line_parts[0][0]) && $line_parts[0][0] === '$') {

src/Psalm/Internal/Scanner/DocblockParser.php

@@ -233,5 +233,13 @@ class DocblockParser
                 + ($docblock->tags['phpstan-var'] ?? [])
                 + ($docblock->tags['psalm-var'] ?? []);
         }
+
+        if (isset($docblock->tags['param-out'])
+            || isset($docblock->tags['psalm-param-out'])
+        ) {
+            $docblock->combined_tags['param-out']
+                = ($docblock->tags['param-out'] ?? [])
+                + ($docblock->tags['psalm-param-out'] ?? []);
+        }
     }
 }

tests/UnusedVariableTest.php

@@ -2135,7 +2135,7 @@ class UnusedVariableTest extends TestCase
                     }
 
                     /**
-                     * @param-out int $c
+                     * @psalm-param-out int $c
                      */
                     function takesByRef(?int &$c) : void {
                         $c = 7;