1. What is Phpdocumentor?
Phpdocumentor is a php-written tool for PHP programs with canonical annotations that can quickly generate API documentation with cross-referencing, indexing, and other functions. The old version is Phpdoc, starting from 1.3.0, renamed Phpdocumentor, the new version adds support for PHP5 syntax, and can be converted to pdf,html,chm in several forms by manipulating the document on the client browser.
When the phpdocumentor is working, it scans the PHP source code under the specified directory, scans the keywords, intercepts the comments that need to be analyzed, then parses the dedicated tag in the comments, generates the XML file, and then builds the corresponding index, generating the XML file, based on the information of the classes and modules that have been parsed. For the generated XML file, use the custom template output for the file in the specified format.
2. Installing Phpdocumentor
As with other pear modules, the installation of Phpdocumentor is also divided into automatic installation and manual installation of two ways, both of which are very convenient:
A Automatic installation via Pear
At the command line, enter
Pear Install Phpdocumentor
b Manual Installation
Download the latest version of Phpdocumentor (now 1.4.0) in http://manual.phpdoc.org/and unzip the content.
3. How to use Phpdocumentor to generate documents
Command line mode:
In the directory where the Phpdocumentor is located, enter
Php–h
A detailed parameter table is given, and several important parameters are as follows:
-F file name to parse, multiple files separated by commas
-D directories to parse, multiple directories separated by commas
-t the stored path of the generated document
-O Output document format, structure 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 the command line to generate documents, you can also operate on the client browser to generate documents, the method is to first put the contents of Phpdocumentor in the Apache directory so that the browser can access to, after access to display the following interface:
Click the Files button to select the php file or folder you want to work with, and you can ignore the processing of some files by specifying file to ignore under that interface.
Then click the Output button to select the path and format of the generated document.
Finally click Create,phpdocumentor will automatically start to generate the document, the bottom will show the progress and status of the build, if successful, will show
Total documentation time:1 seconds
Done
Operation completed!!
Then we can view the generated document, and if it is in PDF format, the name defaults to Documentation.pdf.
4. Add a specification comment to the PHP code
Phpdocument is a document generated from the comments in your source code, so the process of commenting on your program is the process of documenting it.
From this point, Phpdoc urges you to develop good programming habits, as far as possible to use specifications, clear text for your program to make comments, but also more or less to avoid the post-mortem document and document updates are not synchronized some problems.
In Phpdocumentor, comments are divided into document comments and non-document comments.
The so-called document comments, are those placed in front of a particular keyword, the multi-line comment, the specific keyword refers to be able to be phpdoc analysis of keywords, such as Class,var, specific can participate in Appendix 1.
Comments that are not preceded by a keyword or are not canonical are referred to as non-document comments that will not be parsed by Phpdoc and will not appear in the API text you produce.
3.2 How to write a document comment:
All of the documentation comments are a multiline comment starting with/**, called DocBlock in Phpdocumentor, and DocBlock is a software developer's help on a keyword that allows others to know what the keyword is for and how to use it. Phpdocumentor Specifies that a DocBlock contains the following information:
1. Function Summary Area
2. Detailed Description Area
3. Mark Tag
The first line of the document comment is the function description area, which is usually a concise description of the function of the class, method, or function, and the body of the function summary will be displayed in the index area in the generated document. The contents of the function description area can be either a blank line or a. To end
After the function description area is a blank line, followed by the detailed description area. This part of the main is to explain the functionality of your API, use, if possible, there can be examples of usage and so on. In this section, you should focus on the usual use of your API functions or methods, use them, and indicate whether it is cross-platform (if any), for information related to the peace table, you have to distinguish it from those common information, usually by another line, Then write down the considerations or special information on a particular platform that should be sufficient so that your readers can write the appropriate test information, such as boundary conditions, parameter ranges, breakpoints, and so on.
After that is also a blank line, then the document tag tag, indicating some technical information, mainly the most important is the call parameter type, return value is extremely type, inheritance relationship, related methods/functions and so on.
For more information on document tagging, refer to section Fourth: Document tagging.
The documentation comments can also be used for example
Please refer to Appendix Two for a detailed description of this label.
Here is an example of a document comment
/**
* Function add to achieve two number of additions
*
* A simple addition calculation, the function accepts two numbers A, B, returns their and C
*
* @param int Addend
* @param int Summand
* @return Integer
*/
function Add ($a, $b)
{
return $a + $b;
}
The resulting document is as follows:
Add
Integer ADD (int $a, int $b)
[Line 45]
function Add, implement two number of additions
Constants A simple addition calculation, the function accepts two numbers A, B, returns their and C
Parameters
int $a-addend
int $b-Summand
5. Document Tags:
The use of a document tag is a keyword, or other document tag, that the tag can be used to decorate.
All document tags begin with a * after each line. If the mark of @ is out of the middle of a paragraph, the tag will be ignored as normal content.
@access
Scope of Use: Class,function,var,define,module
The tag is used to indicate access rights for the keyword: private, public, or proteced
@author
Specify the author
@copyright
Scope of Use: Class,function,var,define,module,use
Specify copyright information
@deprecated
Scope of Use: Class,function,var,define,module,constent,global,include
Identify unused or deprecated keywords
@example
This tag is used to parse the contents of a file and highlight them. Phpdoc will attempt to read the file contents from the file path that the token gives
@const
Scope of Use: Define
Constants used to indicate define in PHP
@final
Scope of Use: Class,function,var
Indicates that the keyword is a final class, method, property, prohibit derivation, modification.
@filesource
Similar to example, except that the tag directly reads and displays the contents of the currently parsed PHP file.
@global
Indicates the global variable referenced in this function
@ingore
Used to omit the specified keyword from the document
@license
Equivalent to the HTML tag, first the URL, followed by the content to be displayed
such as Baidu
Can write @license http://www.baidu.com Baidu
@link
Similar to license
But you can also refer to any one of the keywords in the document by using link
@name
Specifies an alias for the keyword.
@package
Scope of Use: page-level, define,function,include
Class-Level->class,var,methods
Used to logically divide 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 that the return of a method or function refers to the
@static
Indicates that the off-build word is static.
@var
Indicate variable type
@version
Specifying version information
@todo
Identify areas that should be improved or not implemented
@throws
Indicates that this function may throw an error exception, which can occur in extreme cases
As mentioned above, ordinary document tag tags must be at the beginning of each line at the @ mark, in addition, there is a tag called inline tag, with {@}, including the following:
{@link}
Usage with @link
{@source}
Show the contents of a function or method
6. Some annotation specifications
A. The comment must be
/**
* XXXXXXX
*/
The form
B. For a function that references a global variable, you must use the glboal tag.
C. For variables, the type must be marked with VAR (int,string,bool ... ）
D. Functions must indicate their arguments and return values through the Param and return tags
E. For keywords that appear two or more times or more than two times, you need to ignore the excess by 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 document reading.
G. Use non-document annotations where necessary to improve code legibility.
H. Descriptive content as concise as possible, using phrases rather than sentences.
I. Global variables, static variables and constants must be indicated by corresponding tags
http://www.bkjia.com/PHPjc/319544.html www.bkjia.com true http://www.bkjia.com/PHPjc/319544.html techarticle 1. What is Phpdocumentor? Phpdocumentor is a php-written tool for PHP programs with canonical annotations that can quickly generate API documentation with cross-referencing, indexing, and other functions. The old ...
