PHP Documentation Tools _php

Writing a document is a tedious task that has to be done, and writing API-level documents means a lot of repetitive work and hard-to-maintain consistency. Here we want to recommend to everyone, is supporting PHP5 parsing of the document tool--phpdocumentor.

Using Phpdocumentor, you can automatically extract function and method definitions from your code, as well as automatically handle relationships between classes and generate class tree accordingly. You can also choose to generate HTML, CHM, or PDF documents. With Phpdocumentor, document work has become much easier.



Installing Phpdocumentor

Installing Phpdocumentor under Pear is a very simple matter, just take the CD to the PHP installation directory in the CMD window and enter

Pear Install Phpdocumentor


Pear will download and complete the Phpdocumentor installation yourself.

After the successful installation of Phpdocumentor, there will be an extra phpdoc.bat in the PHP installation directory. This file is the batch file that we used to generate the document.



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 and it will automatically call Phpdocumentor. So the Phpdoc and Phpdocumentor mentioned in the article are actually the same.




In the directory where the Phpdoc.bat is located, enter

Phpdoc–h


Will get a detailed list of phpdocumentor parameters.

Let's take a look at some of the common ones:



-F
File name to parse, multiple files separated by commas

-D
Directories to analyze, multiple directories separated by commas

-T
The stored path of the generated document

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




That's all we'll be using, other commands please read Help's tips.



Trial Phpdocumentor

Let's take the example of phpUnit2 in pear and show you 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


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

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


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




Once the command is complete, our documentation is ready to be created. Enter the target directory that we specified, and open index.html in the browser to see the generated document. The document interface is divided into three parts by frame, on the left is the package information, the lower left is the navigation information, the right is the detailed information rendering page.




The diagram above clearly describes the contents of the document:

indexes, function lists, class lists, file lists, and child packages.

By clicking on the top of the class (es) link, we can see the entire package's class tree clearly.




When we click on one of the classes, we enter the class description page.

The class description page mainly contains the following aspects:



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

L class variables

L Class Constants

L method

L Inherited variables

L Inherited methods: a very useful feature






How about it, isn't it 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 you compile with the Microsoft CHM tool to get the available CHM files.



Generate documents for your own code with Phpdocumentor

Although phpdocumentor can automatically parse some of the information from the code, it is necessary for us to form a detailed document to work with in the coding. In order for Phpdocumentor to read our code, we need to be aware of some coding specifications and add some tags to the comments:





@author
Author information

@const
Constants defined by define

@deprecate
API not recommended for use

@global
Global variables

@package
Package information

@param
function parameters

@return
return value

@see
Reference functions

@since
Introduction Time

@static
static variables

@var
Class member variable




Here is simply a list of some of the commonly used tags, you can read the Phpdocumentor documents, there are very detailed coding specifications. About Phpdocumento introduced here, I hope you 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 web version is easy to install and can be run directly to the Web-accessible directory.





php:5.0.0

OS: Platform Standalone, this article demonstrates OS for Windows

