php - php : @return tag 中的代码注释

Question

我想知道如何按照 PEAR 标准为 `@return 标记、php 中的以下函数编写代码注释。

在遍历 PEAR standards 时，我了解到:

1. Return tags should contain the data type then a description of the data returned : (This part is quite clear)
   

2. Description : By convention, the first noun in the description is the data type of the parameter. Articles like "a", "an", and "the" can precede the noun. The descriptions should start with a phrase. If further description is necessary,follow with sentences.

我的问题是:如何为以下函数编写 @return 标记的说明，如果函数执行成功则返回 true？

function AUTOCODER_writeFile($filename, $code)
{
    $handle = fopen($_POST['db']."/".$filename, "w");  
    fwrite($handle, $code);
    fclose($handle);
    return true;
}

Answer 1

正如您链接的页面所指定的那样，docblock 注释 用于使用 phpDocumentor 生成 PEAR 文档.

您的函数的最小文档 block 注释应如下所示:

/**
 * @param string $filename
 * @param string $code
 * @return bool
 */
function AUTOCODER_writeFile($filename, $code)
{
    $handle = fopen($_POST['db']."/".$filename, "w");  
    fwrite($handle, $code);
    fclose($handle);
    return true;
}

如果 $code 不是字符串，则将 string 替换为正确的类型；如果您的代码以这种方式工作，它只能是字符串或数字(整数或 float )。

要有一个有用的文档 block ，请在其名称后描述每个参数的用途，并放置一行描述该函数的作用。像这样的东西:

/**
 * Store a code into a file
 *
 * @param string $filename the name of the file
 * @param string $code     the value to store
 * @return bool
 */

您可以在 phpDocumentor's documentation 上找到有关如何记录代码的更多信息.它是 PHP 文档的事实标准；许多 IDE 理解它并使用它来帮助您在不运行代码的情况下进行提示和错误检测。