What is phpdocumentor page 1/2

1. What is phpbench entor?
Phpdocumentor is a tool written in PHP. Program It can quickly generate API documents with mutual reference, indexing, and other functions. The old version is phpdoc. It was renamed php‑entor 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 under the specified directory Source code Scan the keywords, extract the comments to be analyzed, analyze the specific tags in the comments, generate the XML file, and then analyze the information of the classes and modules that have been analyzed, create an index to generate an XML file. For the generated XML file, use a custom template 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.0) at http://manual.phpdoc.org/and decompress the content.

3. How to generate a document using phpbench entor
Command Line Method:
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
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.

4. add standard comments to the php Code
phpdocument is a document generated from the comments of your source code, therefore, the process of commenting on your program is the process of compiling the document.
in this regard, phpdoc prompts you to develop good programming habits and try to use specifications and clear text to annotate your program, 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, see Appendix 1.
non-document comments without keywords or non-standard comments are called non-document comments. These comments will not be analyzed by phpdoc or appear in your generated API files.
3.2 document comments:
All document comments are multi-line comments starting with/**, which are called docblock in phpdocumentor, docblock refers to the help information about a keyword written by software developers, so that others can know the specific purpose of this keyword and how to use it. Phpdocumentor specifies that a docblock contains the following information:
1. function Description area
2. detailed description area
3. the first line of tag
document comments is the function description area. The body is generally a brief 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 be passed through an empty line or.
there is a blank line behind the function description area, followed by a detailed description area ,. this section describes in detail the functions and usage of your API. If possible, it can also be used as an example. 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 set up another line, and then write the precautions or special information on a specific platform. This information should be sufficient, this allows your readers to write test information, such as boundary conditions, parameter ranges, and breakpoints.

It is also a blank line, followed by the tag of the document, indicating some technical information, mainly the call parameter type, the return value is extremely type, inheritance relationship, related methods/functions.
For more information about document tagging, see Section 4: Document tagging.
For more information, see appendix 2.
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 added parts

5. Document Tag:
the scope of use of the document tag is a keyword that can be used to modify the tag, or other document tag.
All document tags start with @ After * of 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
This tag is used to specify the access permission for keywords: private, public, or proteced
@ author
specifies the author
@ copyright
scope of use: Class, function, VAR, define, module, use
copyright information
@ deprecated
usage: Class, function, VAR, define, module, constent, global, include
specifies a keyword that is not needed or discarded
@ 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 to
@ const
usage scope: define
is used to specify the define constant in PHP
@ final
scope of use: Class, function, vaR
specifies that the 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
It is equivalent to <A> in an HTML Tag, first the URL, and then the content to be displayed.
For example, <a href = "http://www.baidu.com"> Baidu </a>
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-> define, function, include
Class-> 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
. the comment must be in the form of
/**
* xxxxxxx
*/
B. for functions that reference global variables, the glboal mark must be used.
C. for a variable, you must use VaR to mark its type (INT, String, bool ...)
D. the function must use the PARAM and return tags to specify its parameters and return values
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 labels should be used to link to the corresponding part to facilitate reading the document.
G. Use non-document comments as necessary to improve code readability.
H. The descriptive content should be as concise as possible, and phrases rather than sentences should be used as much as possible.
I. global variables, static variables and constants must be marked with corresponding descriptions