Discussion: How to use PhpDocumentor to generate documents_PHP Tutorial

命令行方式：
　　在phpDocumentor所在目录下，输入phpdoc –h会得到一个详细的参数表，其中几个重要的参数如下：
-f 要进行分析的文件名，多个文件用逗号隔开
-d 要分析的目录，多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式，结构为输出格式：转换器名：模板目录。
　 例如：phpdoc -o HTML:frames:earthli -f test.php -t docs

Web界面生成
　　在新的phpdoc中，除了在命令行下生成文档外，还可以在客户端浏览器上操作生成文档，具体方法是先把PhpDocumentor的内容放在apache目录下使得通过浏览器可以访问到，访问后显示如下的界面：
　　点击files按钮，选择要处理的php文件或文件夹，还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
　　然后点击output按钮来选择生成文档的存放路径和格式.
　　最后点击create，phpdocumentor就会自动开始生成文档了，最下方会显示生成的进度及状态，如果成功，会显示
Total Documentation Time: 1 seconds
done
Operation Completed!!
然后，我们就可以通过查看生成的文档了，如果是pdf格式的，名字默认为documentation.pdf。
给php代码添加规范的注释

PHPDocument是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。
　　从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
　　在phpdocumentor中，注释分为文档性注释和非文档性注释。
　　所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等，具体的可参加附录1.
　　那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在你产生的api文当中。

How to write documentation comments:
All documentation comments are composed of /**The first multi-line comment is called DocBlock in phpDocumentor. DocBlock refers to the help information about a certain keyword written by software developers, so that others can know the specific purpose of this keyword and how to use it. PhpDocumentor stipulates that a DocBlock contains the following information:
1. Function brief description area
2. Detailed description area
3. Tag tag
The first line of documentation comments is the function In the description area, the text generally briefly describes the function of this class, method or function. The text of the brief function description will be displayed in the index area in the generated document. The content of the function description area can be ended by a blank line or.
　
After the function description area is a blank line, followed by a detailed description area. This part mainly describes the functions and uses of your API in detail , if possible, you can also provide examples of usage, etc. In this section, you should focus on clarifying the general purpose and usage of your API functions or methods, and indicate whether it is cross-platform (if involved). For platform-related information, you should treat it differently from general information. , the usual approach is to start a new line, and then write the precautions or special information on a specific platform. This information should be enough so that your readers can write corresponding test information, such as boundary conditions, parameter ranges, Breakpoints, etc.
There is also a blank line after
, and then the document tag, indicating some technical information, mainly the call parameter type, return value and type, inheritance relationship, related methods/functions, etc. wait.

You can also use tags such as in document comments. Please refer to Appendix 2 for details.
An example of a documentation comment
/**
* The function add implements the addition of two numbers
*
* A simple addition calculation, the function accepts two Numbers a and b, return their sum c
*
* @param int addend
* @param int summand
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}
The generated document is as follows:
Add
integer Add(int $a, int $b)
[line 45]
Function add , implement the addition of two numbers
Constants A simple addition calculation, the function accepts two numbers a, b, and returns their sum c
Parameters
• int $a - addend
• int $b - summand
Document tag:
The scope of use of document tags refers to the keywords or other document tags that the tag can be used to modify.
All documentation tags begin with @ after * on each line. If the @ mark appears in the middle of a paragraph, the mark will be treated as normal content and ignored.
@access
Scope of use: class, function, var, define, module
This tag is used to indicate the access permission of keywords: private, public or protected
@author
Specify the author
@copyright
Scope of use: class, function, var, define, module, use
Specify the copyright information
@deprecated
Usage scope: class, function, var, define, module, constent, global, include
Specify unused or obsolete keywords
@example
This tag is used to parse a piece of file content and highlight them. Phpdoc will try to read the file content from the file path given by this tag
@const
Usage scope: define
Used to specify the constant of define in php
@final
Usage scope: class, function, var
Indicates that the keyword is a final class, method, attribute, and derivation and modification are prohibited.
@filesource
Similar to example, except that this tag will directly read the content of the currently parsed php file and display it.
@global
Specifies the global variable referenced in this function
@ingore
Used to ignore the specified keyword in the document
@license
Equivalent to in the html tag, first the URL, then the content to be displayed
For example Summary
phpDocumentor is a very powerful document automatic generation tool. It can help us write standardized comments and generate easy-to-understand, clear-structured documents. Our code upgrades, maintenance, handovers, etc. are all very helpful.
For more detailed instructions about phpDocumentor, you can go to its official website