在phpDoc中，是否需要定义参数类型？

如何解决在phpDoc中，是否需要定义参数类型？

一个老式的例子：

/**
 * @param string $a - test parameter
 */
public function test($a)
{
}

但既然 Php 有类型，我会写：

/**
 * @param $a - test parameter
 */
public function test(string $a)
{
}

因为它有一个参数，所以向 phpdoc 添加 "string" 是冗长的。

解决方法

phpDocumentor docs 声明 @param 需要数据类型字段。这些文档很旧，但我希望使用标签的应用程序仍然遵守该要求。最近，当我有明确的类型提示时，我倾向于完全跳过 @param 标签。

PHPCS 会在您忽略它但有类型提示时发出警报，例如您的示例：

/**
 * @param $arg The arg.
 */
public function foo(int $arg) {

PHPStan 会在您的 @param 标签类型和类型提示不匹配时发出警报，如下所示：

/**
 * @param string $arg The arg.
 */
public function foo(int $arg) {

,

“必要”取决于您用来解析注释的内容（如果有的话）*

如果这是 PHPDocumentor 本身，您将需要坚持它规定的标准。即使它现在在没有类型的情况下工作，也不能保证未来的版本会，正如 Alex Howansky 的回答中提到的，该类型目前被定义为强制性的。来自their manual：

使用@param 标签可以记录函数或方法的单个参数的类型和功能。 当提供时，它必须包含一个类型来指示预期的内容；另一方面，描述是可选的，但在复杂结构（例如关联数组）的情况下建议使用。

如果在参数中省略类型提示，PHPStorm（至少是我面前的版本）会表现得有点奇怪。如果我使用

 * @param $a Some useful comment about my parameter

然后我收到一个关于Undefined class Some的警告。显然，它采用了除 @param 注释和变量名称之外的第一个单词，并假设这是类型。我在 phpdoc 手册中找不到对此行为的引用（在变量之后提供 类型），因此这本身可能是非标准的。有趣的是，如果变量名后的第一个字符是连字符（如您问题中的示例），则警告将被抑制。

我最近看到很多代码完全省略了注释，而是依靠语言的内部类型提示（参数和返回）来完成这项工作。这是完美的，只要您不需要向其中任何一个添加描述。 PHPStorm 会在您提供任何（但不是全部）参数注释时警告您缺少参数注释，这意味着如果您想为一个注释提供注释，那么您需要添加其余的，无论是否注释。

您在问题中提到了冗长，如果所有您担心的是人类可读性，那么请务必忽略类型。 Phpdoc 本身有一个标准，但你绝对不受它的约束。最终，这是您的代码。但是，如果您要发布其他开发人员可能使用的软件包，或者您的任何工具链（从 IDE、静态分析到文档生成本身）对非标准使用不满意，那么您将不得不再次权衡决定。无论哪种方式，都取决于您是唯一一个（人还是机器）阅读您的代码；如果你不是，那么坚持标准，即使这意味着输入一些额外的字符。

--

* 这可能包括实际影响代码运行方式的事情 - PHP 允许您使用 Reflection API 中的 getDocComment 方法获取这些注释。用例往往不包括 @param 注释（更多情况下它是特定于包的东西，如 Doctrine 的 ORM 注释），它们几乎专门用于文档，但我不想过度概括和说这不会对您的代码的实际功能产生影响。