About PHP documentation generation tools
- PHP中文网Original
- 2016-08-20 08:48:191560browse
1. What is phpDocumentor?
PHPDocumentor is a tool written in PHP. For PHP programs with standard annotations, it can quickly generate API documents with cross-reference, indexing and other functions. The old version is phpdoc. Starting from 1.3.0, it has been renamed phpDocumentor. The new version adds support for php5 syntax. At the same time, documents can be generated by operating on the client browser, and the documents can be converted to PDF, HTML, There are several forms of CHM, which are very convenient.
When PHPDocumentor works, it will scan the PHP source code under the specified directory, scan the keywords, intercept the comments that need to be analyzed, then analyze the special tags in the comments, generate an xml file, and then based on the analyzed classes and modules information, establish corresponding indexes, and generate xml files. For the generated xml files, use customized templates to output files in the specified format.
2. Install phpDocumentor
Like other modules under pear, the installation of phpDocumentor is also divided into two methods: automatic installation and manual installation. Both methods are very convenient:
a. Automatically install through pear
Enter
pear install PhpDocumentor
b． Manual installation
Download the latest version of PhpDocumentor (now 1.4.2) at http://manual.phpdoc.org/ and unzip the content.
3. How to use PhpDocumentor to generate documents
a. Command line method
In the directory where phpDocumentor is located, enter
Php -h
and you will get a detailed parameter list. Several important parameters are as follows:
-f To proceed The file name to be analyzed, multiple files are separated by commas
-d The directory to be analyzed, multiple directories are separated by commas
-t The storage path of the generated document
-o The output document format, the structure is the output format :Converter name: template directory.
For 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 browse them on the client Generate documents by operating on the server. The specific method is to first place the content of PhpDocumentor in the apache directory so that it can be accessed through the browser. After access, the following interface is displayed:
Click the files button and select the php file or folder to be processed. You can also ignore the processing of certain files by specifying Files to ignore under this interface.
Then click the output button to select the storage path and format of the generated document.
Finally click create, phpdocumentor will automatically start generating the document, and the progress and status of the generation will be displayed at the bottom. If successful,
Total Documentation will be displayed Time: 1 seconds
done
Operation Completed!!
Then, we can view the generated document. If it is in pdf format, the name defaults to documentation.pdf.
c. Try phpdocumentor
Below we will take phpunit2 in pear as an example to demonstrate how to use phpdocumentor to generate documents.
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 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:phpedit"
After running the above command, phpdocumentor starts to parse the source file and output work information.
After the command is completed, our document has been generated. Enter the target directory we specified and open index.html with a browser to see the generated document. The document interface is divided into three parts by the frame. The upper left is package information, the lower left is navigation information, and the right is a detailed information presentation page.
Index, function list, class list, file list and subpackage. By clicking the class(es) link above, we can clearly see the class tree of the entire package. When we click on one of the classes, we enter the class description page. The class description page mainly includes the following aspects:
[Description: Copyright, author, class hierarchy, etc.], [Class variables], [Class constants], [Methods], [Inherited variables], [Inherited methods: A very useful function]
How about it, is it very detailed? If you want to generate chm, you can change the previous -o parameter to "chm:default: default", so that phpdocumentor will generate a chm project file for you. You only need to compile it with Microsoft's chm tool to get a usable chm file.
d. Chinese garbled solution
If the comment is in Chinese, the language tag of the corresponding template in PhpDocumentor/phpDocumentor/Converters/* needs to be replaced from iso-8859-1 to utf-8, otherwise the generated code will be garbled.
4. Add standardized comments to php code
PHPDocument generates documents from the comments of your source code, so the process of commenting your program is also the process of compiling documentation. From this point of view, PHPdoc encourages you to develop good programming habits and try to use specifications and clear text to annotate your program. At the same time, it more or less avoids some problems of out-of-synchronization between document preparation and document updates afterwards. In phpdocumentor, comments are divided into documentation comments and non-documentation comments. The so-called documentation comments are multi-line comments placed in front of specific keywords. Specific keywords refer to keywords that can be analyzed by phpdoc, such as class, var, etc. For details, please refer to Appendix 1. Comments that do not precede keywords or are not standardized are called non-documentation comments. These comments will not be analyzed by phpdoc and will not appear in the API document you generate.
How to write documentation comments:
All documentation comments are composed of /**The first multi-line comment is called DocBlock in phpDocumentor. DocBlock refers to the help information about a certain keyword written by software developers, so that others can know the specific purpose of this keyword and how to use it. PhpDocumentor stipulates that a DocBlock contains the following information:
1. Function brief description area
2. Detailed description area
3. Tag tag
The first line of the documentation comment is the function description area, and the text is generally a concise explanation The function of this class, method or function, and the text of the function brief description will be displayed in the index area in the generated document. The content of the function description area can be terminated by a blank line or ".". After the function description area is a blank line, followed by a detailed description area. This part mainly describes the function and purpose of your API in detail, including usage examples if possible, etc. In this section, you should focus on clarifying the common purpose and usage of your API functions or methods, and indicate whether it is cross-platform (if involved). For platform-related information, you should treat it differently from general information. . The usual approach is to start a new line and write the precautions or special information on a specific platform. This information should be enough so that your readers can write the corresponding test information, such as boundary conditions, parameter ranges, breakpoints, etc. Wait. After that, there is also a blank line, and then the document tag, indicating some technical information, mainly the call parameter type, return value and type, inheritance relationship, related methods/functions, etc.
About document markup, please refer to -- Document Markup for details. Tags such as can also be used in document comments. Please refer to Appendix 2 for details.
The following is an example of a documentation comment
/**
* The function add implements the addition of two numbers
*
* A simple addition calculation, the function accepts two numbers a and b and returns them The sum of c
*
* @param int addend
* @param int addend
* @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 implement the addition of two numbers
Constants A simple addition calculation , the function accepts two numbers a and b, and returns their sum c
Parameters
? int $a - addend
? int $b - summand
5. Document tags:
The scope of use of document tags refers to the keywords or other document tags that the tag can be used to modify. All documentation tags begin with @ after * on each line. If the @ mark appears in the middle of a paragraph, the mark will be treated as normal content and ignored.
@access
Usage scope: class, function, var, define, module
This tag is used to indicate the access permission of keywords: private, public or protected
@author
Usage scope: class, function, var, define, module, use
Indicate the author
@copyright
Scope of use: class, function, var, define, module, use
Indicate copyright information
@deprecated
Scope of use: class, function, var , define, module, constent, global, include
Indicate unused or obsolete keywords
@example
This tag is used to parse a piece of file content and highlight them. PHPDOC will try to read the file content from the file path given by this tag
@const
Usage scope: define
Used to specify the constants defined in php
@final
Usage scope: class, function, var
Indicates that the keyword is a final class, method, or attribute, and is prohibited from being derived or modified.
@filesource
is similar to example, except that this tag will directly read the content of the currently parsed php file and display it.
@global
Indicates the global variable referenced in this function
@ingore
is used to ignore the specified keyword in the document
@license
is equivalent to in the html tag, the first is URL, followed by the content to be displayed
For example Baidu
can be written as @license http://www.baidu.com Baidu
@link
is similar to license
but you can also point to any keyword in the document through link
@name
Specify an alias for the keyword.
@package
Usage scope: page-level define, function, include
class-level class, var, methods
used to logically group one or several keywords into a group.
@abstrcut
Indicates that the current class is an abstract class
@param
Indicates the parameters of a function
@return
Indicates the return pointer of a method or function
@static
Indicates that the keyword is static of.
@var
Indicate the variable type
@version
Indicate the version information
@todo
Indicate the areas that should be improved or not implemented
@throws
Indicate the error exception that this function may throw, in extreme cases
As mentioned above, ordinary document tags must be marked with @ at the beginning of each line. In addition, there is also a tag called inline tag, represented by {@}, which specifically includes the following:
{@link}
Usage is the same as @link
{@source}
Display the content of a function or method
6. Some comment specifications
a. Comments must be in the form of
/**
* XXXXXXX
*/
b. For functions that reference global variables, glboal tags must be used.
c. For variables, their type (int, string, bool...) must be marked with var
d. Functions must indicate their parameters and return values through param and return markers
e. For two or more For keywords more than once, the redundant ones should be ignored through ingore, and only one should be kept
f. Where other functions or classes are called, link or other tags should be used to link to the corresponding part to facilitate the reading of the document.
g. Use non-documentation comments where necessary to improve code readability.
h. Keep descriptive content concise and to the point, using phrases rather than sentences whenever possible.
i. Global variables, static variables and constants must be described with corresponding tags
7. Summary
Writing documentation is a tedious but necessary task, and writing API-level documentation means a lot of repetition Labor and difficulty maintaining consistency. What we want to recommend to everyone here is the document tool that supports php5 syntax analysis-phpDocumentor. phpDocumentor is a very powerful automatic document generation tool. It can help us write standardized comments and generate easy-to-understand, clear-structured documents, which is very helpful for our code upgrades, maintenance, handover, etc. Using phpDocumentor can not only automatically extract function and method definitions from the code, but also automatically handle the relationship between various classes and generate a class tree accordingly. You can also choose to generate the document into html, chm or pdf. With phpDocumentor, documentation work becomes much easier. For a more detailed description of phpDocumentor, you can check it out on its official website: http://manual.phpdoc.org/.