PHP Documentation Tool_PHP Tutorial

Writing documentation is a tedious but necessary task, and writing API-level documentation means a lot of repeated work and difficulty in maintaining consistency. What we want to recommend to everyone here is the document tool that supports PHP5 syntax analysis-phpDocumentor.
Using phpDocumentor can not only automatically extract function and method definitions from the code, but also automatically handle the relationship between each class and generate a class tree accordingly. You can also choose to generate the document into html, chm or pdf. With phpDocumentor, documentation work becomes much easier.
Install phpDocumentor
Installing phpDocumentor under pear is an extremely simple matter. Just cd to the php installation directory in the cmd window, and then enter
Pear install phpDocumentor
Pear will download it by itself And complete the installation of phpDocumentor.
After phpDocumentor is successfully installed, there will be an additional phpdoc.bat in the php installation directory. This file is the batch file we use to generate documents.
相关知识 ?>
phpDocumentor is an upgraded version of phpDoc. It is a documentation tool specially rewritten to support php5 syntax. When your php version is 5, run phpDoc.bat and it will automatically call phpDocumentor. So the phpDoc and phpDocumentor mentioned in the article are actually the same.

In the directory where phpdoc.bat is located, enter
Phpdoc –h
to get a detailed parameter list of phpDocumentor.
Let’s take a look at a few commonly used ones:
命令解释 ?>
-f
The file name to be analyzed. Multiple files should be separated by commas
-d
Directory to be analyzed, multiple directories separated by commas
-t
Storage path of the generated document
-o
Output document format, the structure is output format: converter name: template directory , for example: HTML:frames:phpedit

These are the only ones we will use. For other commands, please read the help prompts.
Try phpDocumentor

Let’s take phpUnit2 in pear as an example to demonstrate how to use phpDocumentor to generate documents.
First, determine the parameters we need:
命令参数 ?>
-d
C:Program FilesEasyPHP5phpPEARPHPUnit2
-t
C:Program FilesEasyPHP5phpphpunit2doc
-o
HTML:frames:phpedit
According to the above parameters, we combine the following commands:
Phpdoc -d “C:Program FilesEasyPHP5phpPEARPHPUnit2” -t “C:Program FilesEasyPHP5phpphpunit2doc” -o “HTML:frames:phpedit”
After running the above command, phpDocumentor starts to parse the source file and output work information.

After the command is completed, our document has been generated. Enter the target directory we specified and open index.html with a browser to see the generated document. The document interface is divided into three parts by the frame. The upper left is package information, the lower left is navigation information, and the right is a detailed information presentation page.

The above picture clearly describes the contents of the document:
Index, function list, class list, file list and sub-package.
Click on the class(es) link above, and we can clearly see the class tree of the entire package.

When we click on one of the classes, we enter the class description page.
Class description page mainly includes the following aspects:
l Description: Copyright, author, class hierarchy, etc.
l Class variables
l Class constants
l Methods
l Inherited variables
l Inherited method: a very useful function
How about
, is it very detailed? If you want to generate chm, you can change the previous -o parameter to "CHM:default: default", so that phpDocumentor will generate a chm project file for you. You only need to compile it with Microsoft's chm tool to get a usable chm file.
Use phpDocumentor to generate documents for your own code
Although phpDocumentor can automatically analyze some information from the code, forming a detailed document still requires our cooperation in coding. In order for phpDocumentor to understand our code, we need to pay attention to some coding standards and add some tags in comments:
Tags ?>
@author
Author information
@const
defined by define Constant
@deprecate
Deprecated API
@global
Global variable
@package
Package information
@param
Function parameter
@return
Return value
@see
Reference function
@since
Introduction time
@static
Static variable
@var
Class member variable

Here is a simple list of some commonly used Tags. You can read the documentation of phpDocumentor, which contains very detailed coding specifications. That’s all about phpDocumento. I hope everyone can make good use of this tool to standardize their own documents.
PS: phpDocumentor also has a web interface. You can visit http://phpdoc.org to get the web version. The installation of the web version is very simple, just put it in a directory accessible by the web and run it.
环境要求 ?>
PHP: 5.0.0
OS: Platform independent, the OS demonstrated in this article is windows