对 PHP 类和函数的评论？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/6592962/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Comments for PHP class and functions?
提问by sunjie
I would like to add some documentation comments for my (PHP) class and its functions in some standard format so that its easier for others to understand.
我想以某种标准格式为我的 (PHP) 类及其函数添加一些文档注释，以便其他人更容易理解。
I will appriciate if you can give me an example that how you would write comments for following class and function? Thanks.
如果你能给我一个例子，你将如何为下面的类和函数写评论，我会很高兴的？谢谢。
Info about class:
班级信息：
Classname Photos: it has some functions related to uploading the photo and displaying the photos. function names are upload(), display(), delete().
类名照片：它有一些与上传照片和显示照片相关的功能。函数名称为upload(), display(), delete()。
Info about upload function:
上传功能的相关资料：
uploads the resizes and uploads the image and has few parameters as shown below.
上传调整大小并上传图像，参数很少，如下所示。
<?php
class Photos extends CI_Controller
{
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
...
...
returns true or false.
}
回答by prodigitalson
PHPDocumentorstyle is pretty standard and understood by most IDE's and documentation generators.
PHPDocumentor风格非常标准，大多数 IDE 和文档生成器都能理解。
/**
* Photos
*
*
* @package CI
* @subpackage Controller
* @author YOUR NAME <[email protected]>
*/
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)
{
}
}
回答by fatnjazzy
/**
* 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'){
}
This will also be helpful for auto-complete in most known editors
这也将有助于在大多数已知编辑器中自动完成
回答by satnhak
You might want to look at doxygen. If you follow their syntax not only will you be able to auto generate documentation (not actually so useful), but the Zend IDE will give you code hints on auto completion (i.e. it will display the documentation when you start to type the function name).
你可能想看看doxygen。如果您遵循他们的语法，您不仅能够自动生成文档（实际上并不是那么有用），而且 Zend 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.
}
}
回答by SnakE
I would use Natural Docs. The doc comments are easy to read right in the code thanks to human-friendly formatting:
我会使用自然文档。由于人性化的格式，文档注释很容易在代码中阅读：
<?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.
}
