PHP Documentation Tools

Writing a document is a tedious task that you have to do, and writing API-level documentation means a lot of repetitive work and hard to maintain consistency. What we recommend here is a document tool--phpdocumentor that supports PHP5 parsing.

The use of Phpdocumentor not only automatically extracts functions and method definitions from the code, but also automatically processes the relationships between each class and generates class tree accordingly. You can also choose to generate HTML, CHM, or PDF of the document. With Phpdocumentor, document work has become much easier.



Install Phpdocumentor

Installing Phpdocumentor under Pear is an extremely simple thing to do simply by following the CD in the cmd window to the PHP installation directory and entering

Pear Install Phpdocumentor


Pear will download and complete the Phpdocumentor installation on its own.

After Phpdocumentor successfully installed, the PHP installation directory will be more than a phpdoc.bat. This file is the batch file we used to generate the document.

? Related Knowledge?>

Phpdocumentor is an upgraded version of Phpdoc, a document tool that is specifically rewritten to support PHP5 syntax, and when your PHP version is 5 o'clock, run Phpdoc.bat, it automatically invokes 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


Gets a phpdocumentor list of detailed parameters.

From which we choose a few commonly used to look at:

? Command Interpretation?>

-F
File names to be parsed, multiple files separated by commas

-D
Directories to parse, multiple directories separated by commas

-T
The path where the generated document is stored

-O
Output document format, structure is output format: Converter name: Template directory, for example: HTML:frames:phpedit




We're going to use that. Just a few, other commands please read the help message.



Try Phpdocumentor

Let's take a look at the phpUnit2 in pear as an example of how to use Phpdocumentor to generate documents.

First, determine the parameters we need:

? Command parameter?>

-D
C:\Program Files\easyphp5\php\pear\phpunit2

-T
C:\Program Files\easyphp5\php\phpunit2doc

-O
HTML:frames:phpedit


Based on the above parameters, we combine the following command:

phpdoc-d "C:\Program files\easyphp5\php\pear\phpunit2"-T "C:\Program files\easyphp5\php\phpunit2doc"-O "html:frames :p Hpedit "


After running the command above, Phpdocumentor begins parsing the source file and outputting the work information.




Once the command has been run, our document has been generated. Enter the target directory we specified, open the index.html with the browser to see the resulting document. The document interface is divided into three parts, the left is the package information, the bottom left is the navigation information, the right is the detailed information rendering page.




The image above clearly describes the contents of the document:

Index, List of functions, class list, file list, and child package.

Click on the Class (ES) link above to see clearly the entire package's class tree.




We clicked on one class and entered the description page of class.

The class description page mainly contains the following aspects:



L Description: Copyright, author, class level, etc.

L class Variable

L-Class constants

L method

L-Inherited variables

L Inherited methods: a very useful feature






How, 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, as long as the use of Microsoft's CHM tool to compile the available CHM file.



Generate documents for your own code with Phpdocumentor

Although phpdocumentor can automatically analyze some information from the code, it is necessary for us to cooperate in coding to form a detailed document. In order for Phpdocumentor to read our code, we need to pay attention to some coding specifications and add some tags to the comments:



? Tags?>

@author
Author information

@const
Constants defined by define

@deprecate
APIs not recommended for use

@global
Global variables

@package
Package information

@param
function arguments

@return
return value

@see
Reference function

@since
Introduction Time

@static
static variables

@var
Class member variable




Here is simply a list of the commonly used tag, you can read the Phpdocumentor document, which has a very detailed coding specifications. About Phpdocumento is introduced here, I hope everyone can make good use of this tool to standardize their own documents.



Ps:phpdocumentor also has a web interface, and you can access http://phpdoc.org to get the web version. The installation of a web version is simple and can be run directly to a directory that the Web can access.



? Environmental Requirements?>

php:5.0.0

OS: Platform Independent, this article demonstrates that the OS is Windows