PHP document tools

Writing a document is a tedious task that has to be done. writing an API-level document means a large amount of repetitive work and hard-to-maintain consistency. We would like to recommend this document tool phpjavasentor, which supports PHP5 syntax analysis. Using phpjavasentor can not only automatically extract functions and method definitions from the code, but also automatically process various class writing documents, writing API-level documents means a lot of repetitive work and hard-to-maintain consistency. We would like to recommend this document tool phpjavasentor, which supports PHP5 syntax analysis.

PhpDocumentor can be used not only to automatically extract functions and method definitions from the code, but also to automatically process the relationships between classes and generate a class tree accordingly. You can also generate html, chm, or pdf files. With phpjavasentor, the document work is much easier.



Install phpDocumentor

Installing phpjavasentor in pear is extremely simple. you only need to cd in the cmd window to the php installation directory, and then enter

Pear install phpDocumentor


Pear will download and install phpbench entor on its own.

After the phpDocumentor is successfully installed, a phpdoc. bat file is displayed 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 document tool specially designed to support php5 syntax rewriting. when your php version is 5, it runs phpDoc. bat and automatically calls phpDocumentor. So the phpDoc and phpDocumentor mentioned in the article are actually the same.




In the phpdoc. bat Directory, enter

Phpdoc-h


A list of detailed parameters of phpDocumentor is displayed.

Let's select several common ones:



-F
Name of the file to be analyzed. multiple files are separated by commas.

-D
The directory to be analyzed. multiple directories are separated by commas.

-T
Path of the generated document

-O
Output Document Format. The structure is output format: converter name: Template directory, for example: HTML: frames: phpedit




This is what we will use. for other commands, please read the help prompt.



PHP starter entor trial

The following uses phpUnit2 in pear as an example to demonstrate how to use phpDocumentor to generate documents.

First, determine the required parameters:



-D
C: \ Program Files \ EasyPHP5 \ php \ PEAR \ PHPUnit2

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

-O
HTML: frames: phpedit


Based on the preceding parameters, we can combine the following commands:

Phpdoc-d "C: \ Program Files \ EasyPHP5 \ php \ PEAR \ PHPUnit2"-t "C: \ Program Files \ EasyPHP5 \ php \ phpunit2doc"-o "HTML: frames: phpedit"


After running the preceding command, the phpbench entor starts to parse the source file and output work information.




After the command is run, our document has been generated. Access the specified target directory and open index.html with a browser to view the generated document. The document interface consists of three parts: Package information on the top left, navigation information on the bottom left, and detailed information presentation page on the right.




The above figure clearly describes the content of the document:

Index, function list, class list, file list, and sub-package.

Click the class (es) link above to clearly view the class tree of the entire package.




Click a class to go to the class description page.

The Class description page contains the following content:



L description: copyright, author, category level, etc.

L variables

L constants

L method

L inherited variables

L inherited method: a very useful function






How about it? To generate a chm, you can change the-o parameter of the front edge to "CHM: default". In this way, the phpbench entor will generate a chm project file for you, you only need to use Microsoft's chm tool for compiling to obtain the available chm files.



Use phpDocumentor to generate documents for your own code

Although phpDocumentor can automatically analyze some information from the code, we still need to cooperate in coding to form a detailed document. In order to let phpDocumentor understand our code, we need to pay attention to some coding specifications and add some tags in the annotations:





@ Author
Author information

@ Const
Constant defined by define

@ Deprecate
APIs not recommended

@ Global
Global variables

@ Package
Package Information

@ Param
Function parameters

@ Return
Return value

@ See
Reference functions

@ Since
Import time

@ Static
Static variables

@ Var
Class member variables




Here is a simple list of commonly used tags. you can read the phpDocumentor documentation, which contains detailed encoding specifications. This article introduces phpDocumento. I hope you can use this tool to standardize your documents.



PS: phpDocumentor also has Web interface, you can access the http://phpdoc.org to get the Web version. The Web version is easy to install and can be run directly in a directory accessible to the web.





PHP: 5.0.0

OS: The platform is independent. This article demonstrates that the OS is windows