Discussion: How to generate documents using PhpDocumentor

Command line mode:
In the directory where phpDocumentor is located, enter phpdoc?? h and you will get a detailed table of parameters, some of which are important:
-f file name to be parsed, multiple files separated by commas
- The directories to be analyzed by d, with multiple directories separated by commas
-t generated document storage path
-ES12en output document format, structured as output format: Converter name: template directory.
For example, phpdoc-ES16en :frames: ES18en-ES19en. php-t docs

Web interface generation
In the new phpdoc, in addition to generating documents at the command line, it is also possible to generate documents on the client browser. The specific method is to first place the contents of PhpDocumentor in the apache directory so that they can be accessed through the browser. After being accessed, the following interface is displayed:
Click the files button to select the php file or folder to process. You can also omit processing certain files by specifying Files to ignore under this interface.
Then click the output button to select the location and format of the generated document.
Finally, click create, phpdocumentor will automatically start generating documents, the progress and status of the generation will be displayed at the bottom, if successful, will be displayed
Total Documentation Time: 1 seconds
done
Operation Completed!!
We can then view the generated document, which defaults to ES50en.pdf if it is in pdf format.
Add a canonical comment to the php code

PHPDocument generates documentation from comments in your source code, so the process of commenting your program is the process by which you document it.
From this point on, PHPdoc encourages you to develop good programming habits, to use specifications as much as possible, to annotate your programs with clear text, and to more or less avoid the problems of post-documentation and out-of-sync document updates.
In phpdocumentor, annotations are classified as documented and non-documented.
Documentation comments are multi-line comments placed in front of specific keywords that can be analyzed by phpdoc, such as class, var, etc., which can be included in Appendix 1.
Comments that do not precede keywords or are not standard are called non-documentation comments and will not be analyzed by phpdoc and will not appear in the api text that you generate.

How to write documentation comments:
All documented comments are a multi-line comment that starts with /**, known as DocBlock in phpDocumentor, and DocBlock refers to information written by a software developer about a keyword so that others can know its specific purpose and how to use it. PhpDocumentor specifies that an DocBlock contains the following information:
1. Function Description area
2. Detail section
3. Mark tag
The first line of the documentation comment is the function description area. Body 1 is generally a concise description of the function of the class, method, or function. The body of the function description is displayed in the index area in the generated document. The content of the function description area can be ended with 1 blank line or.

After the function description area is a blank line, followed by the detail area. This section is mainly about the function, purpose and, if possible, usage examples of your API. In this part, you should be focused on your API function or method usually use, usage, and indicate whether the cross-platform (if involved), for information platform dependent, you want to and make a difference between the general information, typically 1 row after the other, and then write a note or on a specific platform is special information, this information should be enough, so that your readers can write the corresponding test information, such as boundary conditions and parameters, breakpoints, and so on.

This is followed by the same blank line, followed by the document's tag tag, indicating 1 technical information, primarily the call parameter types, return values and types, inheritance relationships, related methods/functions, and so on.

Examples can also be used in document comments < b > < code > For a detailed description of such labels, please refer to Appendix 2.
An example of a document comment
/**
* add, which adds two Numbers
*
* 1 simple addition calculation, the function takes two Numbers a, b, and returns their and c
*
* @ES110en int addend
* @param int added
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}
The generated documents are as follows:
Add
integer Add( int $a, int $b)
[line 45]
add, which adds two Numbers
Constants 1 simple addition calculation, the function takes two Numbers a, b, and returns their and c
Parameters
The & # 8226; int $a - Addends
The & # 8226; int $b - Additive
Document tags:
The scope of use for a document tag refers to the keywords or other document tags that the tag can be used to decorate.
All document tags begin with an @ after each 1 line *. If the @ sign appears in the middle of a paragraph, it will be ignored as normal content.
@access
Use scope: class, function var, define, module
This tag is used to indicate the access permissions for the keyword: private, public, or proteced
@author
Indicate the author
@copyright
Usage: class, function, var, define, module, use
Indicate copyright information
@deprecated
Use: class, function, var, define, module, constent, global, include
Specifies keywords that are not used or discarded
@example
This tag is used to parse the contents of a 1-paragraph file and highlight them. Phpdoc will attempt to read the file contents from the file path given by the tag
@const
Scope: define
The constant used to specify define in php
@final
Scope: class,function,var
Specifies that the keyword is a final class, method, or property, and prohibits derivation or modification.
@filesource
Similar to example, except that the tag reads directly the contents of the currently parsed php file and displays it.
@global
Specifies the global variable referenced in this function
@ingore
Used to ignore specified keywords in a document
@license
Equivalent to html tag < a > , URL, and then the content to display
For example, < a href = "http: / / www baidu. com" > baidu < /a >
Can write @ license http: / / www baidu. com baidu
@link
Similar to license
But you can also point to any 1 keyword in the document via link
@name
Specify 1 individual name for the keyword.
@package
Scope of use: Page level - > define, function, include
Class level - > class, var, methods
Used to logically group one or more keywords into groups.
@abstrcut
Indicates that the current class is an abstract class
@param
Specifies the parameters of a function
@return
Specifies the return finger of a method or function
@static
Indicates that guan Jian is static.
@var
Specify variable type
@version
Specified version information
@todo
Identify areas that should be improved or not implemented
@throws
Indicates the error exception that this function may throw, and the circumstances in which it occurs
As mentioned above, common document markup tags must begin each line with the @ tag. In addition, there is another type of markup called inline tag, denoted by {@}, specifically including the following types:
{@link}
@ link usage
{@source}
Displays the contents of a 1-paragraph function or method

Some annotation specifications
a. Annotation must be
/**
* XXXXXXX
*/
In the form of
b. For functions that reference global variables, the glboal tag must be used.
var c. The variable to be used to mark its type (int string, bool...).
d. The function must indicate its arguments and return values through the param and return tags
e. For keywords that appear twice or more, ignore the redundant ones through ingore and keep only one
f. Where other functions or classes are called, use link or other tags to link to the appropriate section for easy documentation.
g. Use non-documentation comments where necessary to improve code readability.
Keep descriptive content as brief as possible, using phrases rather than sentences when possible.
Global variables, static variables, and constants must be labeled accordingly

conclusion
phpDocumentor is a very powerful document generation tool, which can help us to write normative comments, generate easy-to-understand, well-structured documents, and greatly help our code upgrade, maintenance, handover, and so on.
More details about phpDocumentor can be found on its official website

Two examples:
Example 1
Example 2