Question

如果我声明函数返回类型，是否必须在php 7中制作docblock？

例如，这样做是否足够？

public function findByLogin(string $login): User
{
    return User::where(User::COL_LOGIN, $login)->first();
}

或者我应该这样做：

/**
 * Find a user by its login.
 *
 * @param string $login
 * @return User
 */
public function findByLogin(string $login): User
{
    return User::where(User::COL_LOGIN, $login)->first();
}

感觉像双重文档。

Answer 1

您不需要在代码中添加PHPDocs-返回类型声明就可以了。

添加PHPDoc的唯一原因是定义更多信息/更特定的类型。

在此处查看此示例：

/**
 * @return string[] An array of strings
 */
public function findByLogin(): array
{
    return ['foo', 'bar'];
}

因此，如果您对返回类型满意，请随时跳过PHPDoc。如果要提供更多有关参数/返回类型的标准化信息，请执行以下操作：添加其他PHPDoc。

PHPStorm之类的工具可帮助保持参数，返回类型和PHPDoc同步。如果两者都不匹配，则会显示警告。

Answer 2

由您决定。

如果方法docblock仅具有参数和返回值类型，则它是无用的，不会为读者提供任何其他信息。

如果docblock提供了更多信息（输入参数的描述或在未找到数据的情况下该方法返回的信息，等等），它会提供附加值，并且有必要编写它。

在您的代码段中，唯一的解释是该方法的作用，但是@param和@return没有提供其他信息，因此我将省略它们。

PHP 7文档块和函数返回类型？

2 个答案: