Question

我想知道如何根据PEAR标准编写代码注释，对于@return标记，以及php中的以下函数。

在浏览PEAR standards时，我了解到：

返回标记应该包含数据类型，然后是对数据的描述   返回的数据：（这部分很清楚）



描述：按照惯例，描述中的第一个名词是参数的数据类型。文章如＆＃34; a＆＃34;，＆＃34;＆＃34;和＆＃34;＆＃34;＆＃34;   可以在名词之前。描述应以短语开头。   如果需要进一步说明，请使用句子。

我的问题是：如何为以下函数编写@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文档。

您的函数的最小docblock注释应如下所示：

/**
 * @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;
}

如果string不是字符串，请将$code替换为/** * Store a code into a file * * @param string $filename the name of the file * @param string $code the value to store * @return bool */的正确类型;如果你的代码以这种方式工作，它只能是一个字符串或一个数字（int或float）。

让一个有用的docblock在其名称后面描述每个参数的用途，并添加一行描述该函数的作用。类似的东西：

if($usercode==1){
   //open file file1.php
}else if($usercode==2){
   //open file file2.php
}else if($usercode==3){
   //open file file2.php
}else{
   // no file to open (this is default condition)
}

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

php中的代码注释：@return标记

1 个答案: