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函数中，因为它不是一个参数。

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

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

Answer 1

PHP-Doc-Comments可以被视为您的模块/类/其他的API文档。由于$ i对您的代码用户不感兴趣 - 为什么要将它放入您的API文档？您的用户无需了解它，因此您不应该告诉他们。对于实际阅读或查看代码的人来说，我可能会感兴趣。因此，您应该添加一个简单的单行注释（//）来描述$ i是什么/做什么，或者添加多行注释（如果需要）。

如何在程序代码中使用DocBlock注释更有效？

1 个答案: