Support @unused-param annotation as an alias.

Related to phan/ProposedAnnotations#1

NEWS.md

@@ -34,6 +34,8 @@ New features (Analysis):
 + Be stricter about checking if callables/closures have anything in common with other types.
 + Preserve more specific phpdoc types when the php 8.0 `mixed` type is part of the real type set.
 + Also emit `PhanPluginUseReturnValueNoopVoid` when a function/method's return type is implicitly void (#4049)
++ Support `@param MyType $name one line description @unused-param` to suppress warnings about individual unused method parameters.
+  This is a new alias of `@phan-unused-param`.
 
 Plugins:
 + Warn and skip checks instead of crashing when running `InlineHTMLPlugin` without the `tokenizer` extension installed. (#3998)

src/Phan/AST/FallbackUnionTypeVisitor.php

@@ -797,7 +797,7 @@ public function visitPrint(Node $node): UnionType
      * @param Node $node
      * A node holding a class name
      *
-     * @return UnionType
+     * @return ?UnionType
      * The set of types that are possibly produced by the
      * given node
      */

src/Phan/AST/UnionTypeVisitor.php

@@ -3036,7 +3036,7 @@ private function visitClassNameNode(Node $node): UnionType
                 ))->getUnqualifiedNameForAnonymousClass();
 
             // Turn that into a fully qualified name, and that into a union type
-            // @phan-suppress-next-line PhanThrowTypeAbsentForCall
+            // @phan-suppress-next-line PhanThrowTypeMismatchForCall
             $fqsen = FullyQualifiedClassName::fromStringInContext(
                 $anonymous_class_name,
                 $this->context
@@ -3060,7 +3060,7 @@ private function visitClassNameNode(Node $node): UnionType
             return StaticType::instance(false)->asRealUnionType();
         }
         if (!Type::isSelfTypeString($class_name)) {
-            // @phan-suppress-next-line PhanThrowTypeAbsentForCall
+            // @phan-suppress-next-line PhanThrowTypeMismatchForCall
             return self::unionTypeFromClassNode(
                 $this->code_base,
                 $this->context,
@@ -3103,13 +3103,13 @@ private function visitClassNameNode(Node $node): UnionType
     }
 
     /**
-     * @param Node $node
+     * @param Node $node @phan-unused-param
      * A node containing a throw expression.
      *
      * @return UnionType
      * `void` is as close as possible to `no-return` or `never` for types currently available in Phan.
      */
-    public function visitThrow(Node $_): UnionType
+    public function visitThrow(Node $node): UnionType
     {
         return VoidType::instance(false)->asRealUnionType();
     }

src/Phan/Language/Element/Clazz.php

@@ -2459,14 +2459,11 @@ private function importMixin(CodeBase $code_base, Type $type): void
     }
 
     /**
-     * Add properties, constants and methods from the
-     * parent of this class
+     * Add constants from the parent of this class
      *
      * @param CodeBase $code_base
      * The entire code base from which we'll find ancestor
      * details
-     *
-     * @return void
      */
     private function importConstantsFromParentClass(CodeBase $code_base): void
     {
@@ -2503,8 +2500,6 @@ private function importConstantsFromParentClass(CodeBase $code_base): void
      * @param CodeBase $code_base
      * The entire code base from which we'll find ancestor
      * details
-     *
-     * @return void
      */
     private function importParentClass(CodeBase $code_base): void
     {

src/Phan/Plugin/Internal/VariableTrackerPlugin.php

@@ -354,8 +354,8 @@ private function warnAboutVariableGraph(
                 if ($issue_type === Issue::UnusedPublicMethodParameter) {
                     // Narrow down issues about parameters into more specific issues
                     $doc_comment = $method_node->children['docComment'] ?? null;
-                    if (is_string($doc_comment) && \preg_match('/@param[^$]*\$' . \preg_quote($variable_name) . '\b.*@phan-unused-param\b/', $doc_comment)) {
-                        // Don't warn about parameters marked with phan-unused-param
+                    if (is_string($doc_comment) && \preg_match('/@param[^$]*\$' . \preg_quote($variable_name) . '\b.*@(phan-)?unused-param\b/', $doc_comment)) {
+                        // Don't warn about parameters marked with @phan-unused-param or @unused-param
                         continue;
                     }
                     $issue_type = $this->getParameterCategory($method_node);

tests/plugin_test/expected/186_phpdoc_in_wrong_comment.php.expected

@@ -0,0 +1 @@
+src/186_phpdoc_in_wrong_comment.php:2 PhanPluginPHPDocInWrongComment Saw possible phpdoc annotation in ordinary block comment "/*\n * @param string $value\n */". PHPDoc comments should start with "/**", not "/*"

tests/plugin_test/expected/187_unused_param.php.expected

@@ -0,0 +1,2 @@
+src/187_unused_param.php:9 PhanUnusedGlobalFunctionParameter Parameter $fourth is never used
+src/187_unused_param.php:9 PhanUnusedGlobalFunctionParameter Parameter $second is never used

tests/plugin_test/src/186_phpdoc_in_wrong_comment.php

@@ -0,0 +1,8 @@
+<?php
+/*
+ * @param string $value
+ */
+function my_strlen($value) {
+    return strlen($value);
+}
+echo my_strlen('test');

tests/plugin_test/src/187_unused_param.php

@@ -0,0 +1,13 @@
+<?php
+
+/**
+ * @param string $first @unused-param description
+ * @param string $second @unused not recognized
+ * @param string $third description @phan-unused-param
+ * @param string $fourth description
+ */
+function test187($first, $second, $third, $fourth) {
+    echo __FUNCTION__ . "\n";
+}
+
+test187('a', 'b', 'c', 'd');