使用 PHP7 时，是否需要用 PHPDoc 记录方法？

Question

在PHP7中，当一个方法设置给定的参数类型和结果类型时，是否有必要在PHPDoc中再次记录它们？

自从

function foo(string $text): bool
{
    return true;
}

等同于

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

是否需要复制这些信息？

/**
 * @param string $text
 * @return bool
 */
function foo(string $text): bool
{
    return true;
}

编辑：我不使用 PHPDoc 生成我的代码文档，而是在 PHPStorm 的帮助下为我和我的同事保持方法的一致性。

Answer 1

文档块是编码人员可以用来解释函数功能的东西，~~它将被 PHP 解析器~~ 忽略（请参阅下面的编辑），因为这只是一个注释，最好在每个函数和方法上方放置一个文档块，因为当某人（或您）阅读代码时，更容易看到函数的作用。

A IDE 通常使用 docblock 来自动完成，但是当块与代码 [=30] 不匹配时，docblock 将被 string 和 :bool 覆盖=]

然而

function foo(string $text): bool
{
    return true;
}

不等同于

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

第一个示例中的 :bool 强制 foo() return 是 true 或 false，其他任何内容和 PHP 都将尝试将 return 转换为该类型或抛出致命错误。它与 $text 的类型提示 string 相同。第一个参数必须是字符串类型的值，否则 PHP 尝试将其转换为字符串，否则将抛出致命错误

@return bool 和 @param string 根本不强制执行任何内容，只是说预期的 return 是 true 或 false

举个例子：

function foo(string $a) :bool
{
    var_dump($a); // string '10'
    return "string";
}

var_dump(foo(10)); // bool true

没问题，PHP 可以将 10 转换为字符串，而 "string" 是 true 以下虽然有问题

function foo(PDO $a) :bool 
{
    var_dump($a);
    return "string";
}

var_dump(foo(10)); // fatal error, 10 is not PDO and can not be cast to PDO

使用 docblock 将使最后一个工作（可能运行进一步解决其他问题，因为您可能正在尝试对 PDO 对象做一些事情）

注意：PHP 尚不支持混合类型类型提示（即字符串|数组），这仍然需要通过在文档块中指定来完成

编辑：
正如@inwerpsel 在评论中指出的那样，我关于 PHP 解析器忽略文档块的说法是不正确的。 ReflectionClass.

可以在运行时读取文档块

使用 PHP7 时，是否需要用 PHPDoc 记录方法？

When using PHP7, is it necessary to document methods with PHPDoc?

php

phpdoc

php-7