一个老式的例子：
/**
* @param string $a - test parameter
*/
public function test($a)
{
}
但既然 PHP 有类型，我会写：
/**
* @param $a - test parameter
*/
public function test(string $a)
{
}
因为它有一个参数，所以在phpdoc中添加“字符串”是冗长的。
【问题讨论】：
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
然后我收到关于未定义类 Some 的警告。显然，它采用了除@param 注释和变量名之外的第一个单词，并假设这是类型。我在 phpdoc 手册中找不到对这种行为的引用（提供类型 after 变量），所以它本身可能是非标准的。有趣的是，如果变量名之后的第一个字符是连字符（如您问题中的示例所示），则警告将被抑制。
我最近看到很多代码完全省略了注释，并依赖于语言的内部类型提示（参数和返回）来完成这项工作。这是完美的，只要您不需要为其中任何一个添加描述。当您提供任何（但不是全部）参数注释时，PHPStorm 会警告您缺少参数注释，这意味着如果您想为一个注释提供注释，那么您需要添加其余的，无论是否注释。
您在问题中提到了冗长，如果 all 您关心的是人类可读性，那么请务必忽略类型。 Phpdoc 本身有一个标准，但你绝对不受它的约束。最终，这是您的代码。但是，如果您要交付其他开发人员可能使用的软件包，或者如果您的任何工具链（从 IDE、通过静态分析到文档生成本身）对非标准使用不满意，那么您将不得不再次权衡决定。无论哪种方式，都取决于您是否是唯一一个（人或机器）阅读您的代码的人；如果你不是，那么坚持标准，即使这意味着要输入一些额外的字符。
--
* 这可能包括实际影响代码运行方式的事情 - PHP 允许您使用 Reflection API 中的 getDocComment 方法获取这些注释。这方面的用例往往不包括 @param 注释（通常是特定于包的东西，如 Doctrine 的 ORM 注释），它们几乎专门用于文档，但我不想过度概括并说这不会影响代码的实际功能。
【讨论】：