我想以某种标准格式为我的(PHP)类及其函数添加一些文档注释，以便其他人更容易理解。
如何为下面的类和函数编写注释?
类信息:
Classname Photos:有一些上传照片和显示照片的相关功能。功能名称为upload(), display(), delete()
上传功能信息:
上传调整大小和上传图像，并有如下所示的几个参数。
<?php
class Photos extends CI_Controller
{
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
...
...
returns true or false.
}
?>
PHPDocumentor样式是非常标准的，并且被大多数IDE和文档生成器所理解。
/**
* Photos
*
*
* @package CI
* @subpackage Controller
* @author YOUR NAME <YOUREMAIL@domain.com>
*/
class Photos extends CI_Controller
{
/**
*
* Uploads a file
*
* @param string $file_name description
* @param string $new_name description
* @param integer $new_width description
* @param integer $new_height description
* @param string $directory description
* @return boolean
*/
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
}
}
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional'){
}
这对大多数编辑器的自动完成也很有帮助。
你可能想看看氧。如果你遵循它们的语法，你不仅可以自动生成文档(实际上不是很有用)，而且Zend Studio IDE会给你自动完成的代码提示(即，当你开始输入函数名时，它会显示文档)。
/*! 'brief My Photo Class
* Does some stuff with photos
*/
class Photos extends CI_Controller
{
/*! 'brief Uploads a file
* 'param $file_name The name of the file
* ...
* 'returns A value indicating success
*/
public function upload($file_name, $new_name, $new_width, new_$height, $directory)
{
...
...
returns true or false.
}
}
我会使用Natural Docs。由于采用了人性化的格式，文档注释在代码中很容易阅读:
<?php
/*
Class: Photos
Some functions related to uploading the photo and displaying the photos.
*/
class Photos extends CI_Controller
{
/*
Function: upload
Upload a photo to the server so that you can later <display> it.
Arguments:
file_name - name of the file
new_name - name of the file on the server
new_width - resize to this before uploading
new_height - resize to this before uploading
Returns:
true or false.
See Also:
<display>
<delete>
*/
public function upload($file_name, $new_name, $new_width, new_$height, $directory)
{
...
...
returns true or false.
}