PHP document generation tools

1. What is phpbench entor? PHPDocumentor is a tool written in PHP. For php programs with standardized annotations, it can quickly generate API documents with functions such as mutual reference and indexing. The old version is phpdoc, Which is renamed php‑entor from 1.3.0. The new version supports the php5 syntax. At the same time, you can

1. What is phpbench entor? PHPDocumentor is a tool written in PHP. For php programs with standardized annotations, it can quickly generate API documents with functions such as mutual reference and indexing. The old version is phpdoc, Which is renamed php‑entor from 1.3.0. The new version supports the php5 syntax. At the same time, you can

1. What is phpbench entor?

PHPDocumentor is a tool written in PHP. For php programs with standardized annotations, it can quickly generate API documents with functions such as mutual reference and indexing. The old version is phpdoc. It was renamed phpDocumentor from 1.3.0. The new version is added with support for the php5 syntax. At the same time, you can generate documents through operations on the client browser, the document can be converted to PDF, HTML, or CHM format, which is very convenient.

When PHPDocumentor is working, it will scan the php source code under the specified directory, scan the keywords, extract the comments to be analyzed, and then analyze the specific tags in the comments to generate xml files, then, an index is created based on the analyzed class and module information to generate an xml file. For the generated xml file, a custom template is used to output the file in the specified format.

2. Install phpDocumentor

Like other pear modules, phpbench entor can be installed automatically or manually. Both methods are very convenient:

A. Automatic Installation through pear

Enter

Pear install PhpDocumentor

B. Manual Installation

Download the latest phpbench entor (1.4.2) at http://manual.phpdoc.org/and decompress the content.

3. How to generate a document using phpbench entor

A. Command Line

Enter

Php-h

A detailed parameter table is displayed. Several important parameters are as follows:

-F name of the file to be analyzed. Multiple files are separated by commas.

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

-T: storage path of the generated document

-O output file format. The structure is output format: converter name: Template directory.

Example: phpdoc-o HTML: frames: earthli-f test. php-t docs

B. Web Interface Generation

In the new phpdoc, in addition to generating documents under the command line, you can also generate documents on the client browser, the specific method is to put the content of PhpDocumentor under the apache directory so that it can be accessed through a browser. The following interface is displayed after access:

Click the files button and select the PHP file or folder to be processed. You can also specify Files to ignore on this interface to ignore the processing of some files.

Click the output button to select the path and format of the generated document.

Finally, click create. The phpdocumentor automatically starts generating the document. The progress and status of the generated document are displayed at the bottom.

Total Documentation Time: 1 seconds

Done

Operation Completed !!

Then, we can use the generated document. If it is in the simplified format, it is named documentation.pdf.

C. Try phpjavasentor

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.

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:

[Description: copyright, author, class level, etc.], [class variables], [class constants], [Methods], [inherited variables], and [inherited methods: 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.

D. Solutions to Chinese garbled characters

4. Add standard comments to the php code

PHPDocument is to generate a document from the comments of your source code. Therefore, the process of commenting your program is the process of compiling the document. From this point on, PHPdoc prompts you to develop good programming habits, try to use specifications, clear text for your program to make comments, at the same time, it also avoids the problem of non-sync preparation of documents and updates later. In phpdocumentor, annotations are classified into document comments and non-document comments. Document comments are multi-line comments placed before specific keywords. specific keywords refer to keywords that can be analyzed by phpdoc, such as class and var. For details, refer to Appendix 1. Comments that are not preceded by keywords or are not standardized are called non-document comments. These comments will not be analyzed by phpdoc or appear in your generated api text.

How to Write document comments:

All document comments are a multi-line comments starting with/**. In phpDocumentor, DocBlock refers to the help information written by software developers about a keyword, this allows others to know the specific purpose of this keyword and how to use it. PhpDocumentor specifies that a DocBlock contains the following information:

1. Function overview Area

2. Detailed description area

3. tag

The first line of document comments is the function description area. The body is generally a concise description of the functions of this class, method, or function, the body of the function description is displayed in the index area in the generated document. The content in the function description area can end with a blank line or. There is a blank line behind the function description area, followed by a detailed description area. This section mainly describes the functions and usage of your API, and examples of useful methods if possible. In this section, you should focus on the common usage and usage of your API functions or methods, and specify whether it is cross-platform (if involved). For platform-related information, you need to treat it differently from general information. The common practice is to create another line and then write the precautions or special information on a specific platform. This information should be sufficient so that your readers can write the relevant test information, such as the boundary condition, parameter range, and breakpoint. It is also a blank line, followed by the tag of the document, indicating some technical information, mainly calling the parameter type, return value extremely type, inheritance relationship, related methods/functions, and so on.

Below is an example of document comment

/**

* Add the function to add two numbers.

*

* In a simple addition calculation, the function accepts two numbers a and B and Returns their and c

*

* @ Param int Addition

* @ Param int add count

* @ Return integer

*/

Function Add ($ a, $ B)

{

Return $ a + $ B;

}

The generated document is as follows:

Add

Integer Add (int $ a, int $ B)

[Line 45]

Function add to add two numbers

Constants is a simple addition calculation. The function accepts two numbers a and B and Returns their and c

Parameters

? Int $ a-addend

? Int $ B-Number of appenders

5. Document Tag:

The scope of use of a document tag is a keyword that can be used to modify a document tag, or other document tag. All document tags start with @ after each line. If @ is marked in the middle of a passage, the mark will be ignored as common content.

@ Access

Usage scope: class, function, var, define, module

Indicates the access permission for a keyword: private, public, or proteced.

@ Author

Usage scope: class, function, var, define, module, use

Specify author

@ Copyright

Usage scope: class, function, var, define, module, use

Copyright information

@ Deprecated

Usage scope: class, function, var, define, module, constent, global, include

Specify unnecessary or obsolete keywords

@ Example

This tag is used to parse the content of a file and highlight it. PHPDOC will try to read the file content from the file path marked

@ Const

Scope of use: define

Used to specify the define constant in php

@ Final

Usage scope: class, function, var

Specifies that a keyword is a final class, method, or attribute, and cannot be derived or modified.

@ Filesource

Similar to example, however, this tag will directly read and display the content of the currently resolved PHP file.

@ Global

Specifies the global variables referenced in this function.

@ Ingore

Used to ignore specified keywords in the document

@ License

For example, Baidu

Can write @ license http://www.baidu.com Baidu

@ Link

Similar to license

However, you can refer to any keyword in the document through link.

@ Name

Specify an alias for the keyword.

@ Package

Scope of use: page-level define, function, include

Class, var, methods

It is used to logically group one or more keywords into one group.

@ Shortcut

Indicates that the current class is an abstract class.

@ Param

Specify the parameters of a function.

@ Return

Specifies the return value of a method or function.

@ Static

Indicates that the word is static.

@ Var

Variable type

@ Version

Specify version information

@ Todo

Specify the areas to be improved or not implemented

@ Throws

Indicates the error exception that this function may throw.

As mentioned above, the mark of common documents must start with @ at the beginning of each line. In addition, there is also a Mark called inline tag, which is represented by {@}, including the following:

{@ Link}

Usage: @ link

{@ Source}

Display the content of a function or Method

6. Some annotation specifications

A. The comment must be

/**

* XXXXXXX

*/

Format

B. The glboal mark must be used for functions that reference global variables.

C. For variables, you must use var to mark their types (int, string, bool ...)

D. The function must specify its parameters and return values through param and return tags.

E. For keywords that appear twice or more times, ignore unnecessary keywords through ingore and retain only one keyword.

F. When other functions or classes are called, link or other markup should be used to link to the corresponding part for easy reading of the document.

G. Use non-document comments as necessary to improve ease of coding.

H. The descriptive content should be as concise as possible and use phrases instead of sentences as much as possible.

I. global variables, static variables and constants must be marked with corresponding descriptions

7. Summary

Writing documents is a tedious but hard-to-do job, and writing API-level documents 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. PhpDocumentor is a very powerful Automatic Document generation tool. It helps us write standard comments to generate documents that are easy to understand and have a clear structure, it is very helpful for code upgrade, maintenance, and handover. 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. For more detailed descriptions of phpDocumentor, you can go to its official website: http://manual.phpdoc.org/check.