1

我正在编写程序 PHP 风格的脚本，但仍想尽我所能记录所有内容。这就是我使用 DocBlock 注释的原因。作为新手，我想知道如何在以下场景中使用它们（专门为此问题编写的代码）：

/**
 * Checks string length
 *
 * @param int $max_length  an integer determining the string length to check against
 * @param string $string  the string to be checked
 * @return bool  a boolean value indicating if the string is shorter or longer
 *               than $max_length. True if shorter, false if longer
 */
function check_length( $max_length = 2, $string ) {
    $i = 0;

    if( strlen( $string ) > $max_length )
        return false;

    return true;
}

让我们假设$i该功能需要。我应该如何记录它？我不能把它放在函数 DocBlock 中，因为它不是一个参数。

该示例在该类中有两个类似的变量，但由于我没有编写面向对象的代码，所以我不能放在$i函数之外（或者只是不想改变我的编码风格以能够使用 DocBlocks）。

另一种方法是不记录这些“内部”变量，因为对于使用该函数，它们并不重要。

4

1 回答 1

1

PHP-Doc-Comments 可以被视为您的模块/类/任何东西的 API 文档。由于 $i 对您的代码的用户不感兴趣 - 为什么要将它放入您的 API 文档中？您的用户不需要知道它，因此您不应该告诉他们。$i 可能对实际阅读或审查您的代码的人很感兴趣。因此，如果需要，您应该添加一个简单的单行注释 (//) 来描述 $i 是/做什么或多行注释。

于 2014-04-12T20:08:33.513 回答