PHP documentation tool
--Phpdocumentor
Easy @ phpe / text
Write documents is a boring job that has to be done, and writing API-level documents means a large number of repetitive labor and difficult consistency. Here we have to recommend it to everyone, which is a documentation tool that supports PHP5 grammar analysis - phpdocumentor.
Use phpoCumentor not only automatically extract functions and method definitions from the code, but also automatically handle the relationship between the various CLASs, and generates the Class Tree accordingly. You can also choose to generate a document to HTML, CHM, or PDF. With PHPDocumentor, the documentation work has been relaxed.
Install PHPDocumentor
Installing phpdocumentor under PEAR is an extremely simple matter, just need to CD to the PHP installation directory in the CMD window, then enter
Pear install phpdocumentor
PEAR will download and complete the installation of phpDocumentor.
After the PHPDocumentor is successfully installed, there will be a phpdoc.bat in the PHP installation directory. This file is the batch file we used to generate a document.
PHPDocument is the upgrade version of phpdoc, which is a document tool that is derived for supporting PHP5 syntax. When your PHP version is 5, run phpdoc.bat, which will automatically call phpdocumentor. Therefore, the phpdoc and phpdocumentor mentioned in the article are actually the same.
In the directory where phpdoc.bat is located
PHPDOC -H
Will get a list of PHPDocumentors.
We have selected several commonly used to see:
-f
To analyze the file name, multiple files are divided by commas
-d
To analyze the catalog, multiple directory segmented
-t
The stored path of the generated document
-o
Output document format, structure is output format: Converter Name: Template directory, for example: html: frames: phpedit
What we will use will, please read the Help prompt information.
Try phpdocumentor
Below we take PHPUNIT2 in PEAR, demonstrate how to use phpDocumentor to generate a document.
First, determine the parameters we need:
-d
C: / program files / easyphp5 / php / pear / phpUnit2
-t
C: / program files / easyphp5 / php / phpUnit2doc
-o
HTML: Frames: phpedit
According to the parameters on the upper side, we combine the down command:
PHPDOC -D "C: / Program files / easyphp5 / php / pear / phpUnit
2"
-t "c: / program files / easyphp5 / php / phpUnit2doc" -o "html: frames: phpedit"
After running the command, phpdocumentor starts parsing the source file and outputs working information.
After the command is running, our documentation has been generated. Enter our designated target directory, open index.html with your browser to see the generated document. The document interface is divided into three parts by frame, and the top left is package information. The lower left is navigation information, and the right side is a detailed information presentation page.
The picture on the upper side clearly describes the contents of the document:
Index, function list, class list, file list, and sub-package.
Click on the Class (ES) link on the previous side, we can clearly see the Class Tree of the entire package.
We click on one of the Class to enter the Class's description page. The Class Description page mainly includes the following aspects:
l Description: copyright, author, class level, etc.
L variable
l
l method
l Inherited variables
l Inheritance: Very useful features
How is it, is it very detailed? If you want to generate a CHM, you can change the front -o parameter to "CHM: Default: Default" so that phpDocumentor will generate a good CHM project file for you, just compile with Microsoft's CHM tools to get available CHM files.
Generate a document for your own code with phpdocumentor
Although phpDocumentor can automatically analyze some information from the code, but to form a detailed document or we need to cooperate in the encoding. In order to let PHPDocumentor read our code, we need to pay attention to some coding specifications and add some TAGs in the comments:
@Author
author information
@Const
Constant defined by define
@DepRecate
Not recommended API
@global
Global variable
@package
Package information
@Param
Function parameters
@Return
return value
@see
Reference function
@since
Introduction time
@static
Static variable
@var
Class member variable
Here is simply listed some common TAGs, you can read the PHPDocumentor's documentation, there is a very detailed code specification. About phpdocumento introduces here, I hope everyone can use this tool to regulate their documentation.
PS: phpdocumentor also has a web interface, you can access http://phpdoc.org to get the Web version. The Web version is installed very simple and can be running directly to the web that can be accessed.
PHP:
5.0.0
OS: Platform Independence, this article Demo OS for Windows
