如何在过程代码中更有效地使用DocBlock注释

Question

我正在用过程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中，因为它不是一个参数。

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

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

Answer 1

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