使用 PHPDoc 显示多行 @param 的正确方法是什么？答案

【问题标题】：What is the correct way to display a multi-line @param using PHPDoc?使用 PHPDoc 显示多行 @param 的正确方法是什么？
【发布时间】：2014-04-28 23:49:56
【问题描述】：

根据我所做的研究，我似乎找不到正确的方法来格式化多行 phpdoc @param 行。推荐的方法是什么？

这是一个例子：

/**
 * Prints 'Hello World'.
 *
 * Prints out 'Hello World' directly to the output.
 * Can be used to render examples of PHPDoc.
 *
 * @param string $noun Optional. Sends a greeting to a given noun instead.
 *                     Input is converted to lowercase and capitalized.
 * @param bool   $surprise Optional. Adds an exclamation mark after the string.
 */
function helloYou( $noun = 'World', $surprise = false ) {

    $string = 'Hello ' . ucwords( strtolower( $string ) );

    if( !!$surprise ) {
        $string .= '!';
    }

    echo $string;

}

这是正确的，还是不添加缩进，还是将所有内容都放在一条长线上？

【问题讨论】：

为什么要多行？如果您需要更详细地描述，请保持更长的行，请在@params之后进行
我不想把它全部放在一行上，因为它越长越难以阅读。我也不确定你的第二选择是什么意思。
我认为解析标签的文档生成器不会关心那个缩进，所以当你直接查看代码和文档块时，你想怎么看它真的很重要。一些编码标准确实规定了缩进，例如PEAR 标准规定数据类型应该对齐，varnames 应该对齐，并且描述应该对齐。因此，在您的示例中，数据类型和 varnames 与标准对齐，但 $noun 的描述应进一步缩进，以与 $surprise 的描述保持一致。一个更简单的选择是将整个描述放在下一行，缩进 4 个空格。
注意：PSR-2 会抱怨行太长，即使是在注释块中。

标签： php documentation phpdoc

【解决方案1】：

你可以这样做：

 /**
 *
 * @param string $string Optional. Sends a greeting to a given noun instead.
 *                       Input is converted to lowercase and capitalized.
 * @param bool $surprise
 */
function helloYou( $string = 'World', $surprise = false )
{
    $string = 'Hello ' . ucwords( strtolower( $string ) );

    if( !!$surprise ) {
        $string .= '!';
    }

    echo $string;
}

所以你的例子很好，除了一件事：PHPDoc @param 需要与 PHP 参数具有相同的名称。您在文档中将其称为 $noun，在实际代码中将其称为 $string。

【讨论】：

参数名称匹配不正确的好地方。谢谢！