1. What is Phpdocumentor?
Phpdocumentor is a tool written in PHP, and for PHP programs with canonical annotations, it can quickly generate API documents with cross-references, indexes, and so on. The old version is Phpdoc, starting with 1.3.0, renamed Phpdocumentor, the new version adds support for the PHP5 syntax, and can be easily converted to pdf,html,chm several forms by manipulating the documentation on the client browser.
Phpdocumentor work, will scan the specified directory under the PHP source code, scan the keyword, intercept the need to analyze the annotation, and then analyze the annotations of the special tag, generate the XML file, and then based on the analysis of the class and module information, build the corresponding index, generate XML files, For the generated XML file, use a custom template to output the file in the specified format.
2. Install Phpdocumentor
Like other pear modules, the Phpdocumentor installation is also divided into automatic installation and manual installation of two ways, both of which are very convenient:
A Automatic installation via Pear
Enter at the command line
Pear Install Phpdocumentor
b Manual Installation
Download the latest version of the Phpdocumentor (now 1.4.0) in http://manual.phpdoc.org/and unzip the content.
3. How to use Phpdocumentor to generate documents
Command-line method:
In the directory where Phpdocumentor is located, enter
Php–h
A detailed parameter list is obtained, with several important parameters as follows:
-f file name to be parsed, multiple files separated by commas
-D directories to parse, multiple directories separated by commas
The storage path of the document generated by-t
-O Output document format, structure is output format: Converter name: Template directory.
For example: Phpdoc-o html:frames:earthli-f test.php-t Docs
Web Interface Generation
In the new Phpdoc, in addition to generating documents at the command line, you can also manipulate the documentation on the client browser by placing the contents of the Phpdocumentor in the Apache directory so that it can be accessed through the browser, and then the following interface is displayed:
Click the Files button to select the php file or folder you want to process, and you can also ignore the processing of some files by specifying the file 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 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!!
We can then view the generated document, and if it is in PDF format, the name defaults to Documentation.pdf.
4. Add a specification comment to your PHP code
Phpdocument is a document generated from the comments in your source code, so the process of annotating your program is the process of documenting it.
From this point of view, Phpdoc prompted you to develop good programming habits, as far as possible use of specifications, clear text for your program to make comments, and more or less also avoid the subsequent preparation of documents and document updates are not synchronized with some of the problems.
In Phpdocumentor, comments are divided into document and non-document comments.
A document annotation is a multiline comment that is placed in front of a particular keyword, which is a keyword that can be phpdoc analyzed, such as Class,var, and is available in Appendix 1.
Comments that are not in front of the keyword or that are not canonical are referred to as Phpdoc comments and will not be parsed by the analysis and will not appear in the API text that you produce.
3.2 How to write a document comment:
All of the documentation comments are a multiline comment started by/**, called DocBlock in Phpdocumentor, and DocBlock refers to the help that a software developer writes about a keyword that allows others to know the specific purpose of the keyword and how to use it. Phpdocumentor stipulates that a DocBlock contains the following information:
1. function Brief Area
2. Detailed Description Area
3. Tagged tag
The first line of a document annotation is a functional description area, where the body is typically a concise description of the function of the class, method, or function, and the body of the feature brief is displayed in the indexed area in the resulting document. The contents of a feature description area can be passed through a blank line or. To end
The functional description area is followed by a blank line, followed by a detailed description area. This section is mainly about the function of your API, use, if possible, can also use examples, etc. In this section, you should highlight the usual use of your API function or method, and indicate whether it is cross-platform (if it is involved), and you need to differentiate it from the generic information, usually by a different line, Then write notes on a particular platform or special information that should be sufficient so that your readers can write the appropriate test information, such as boundary conditions, parameter ranges, breakpoints, and so on.
Then it is also a blank line, followed by the document tag tag, indicating some technical information, mainly the invocation of the parameter type, the return value extremely type, the inheritance relation, the related method/function and so on.
For more information about document tags, please refer to section Fourth: Document tags.
Tags such as <b> <code> can also be used in documentation comments, please refer to Appendix two for more information.
The following is an example of a document annotation
/**
* Function Add, to achieve the addition of two numbers
*
* A simple addition calculation, the function accepts two numbers A, B, returns their and C
*
* @param int Addends
* @param int Summand
* @return Integer
*/
function Add ($a, $b) {
return $a + $b;
}
The document is generated as follows:
Add
Integer ADD (int $a, int $b)
[Line 45]
function add to achieve two-digit addition
Constants A simple addition calculation, the function accepts two numbers A, B, returns their and C
Parameters
int $a-addends
int $b-Summand
5. Document markup:
The use of a document tag is a keyword, or other document tag, that the tag can be used to decorate.
All document tags are preceded by @ at the end of each line. If the mark in the middle of a passage comes out @, the mark will be ignored as plain content.
@access
Scope of Use: Class,function,var,define,module
This tag is used to indicate access rights for keywords: 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
Indicate unused or obsolete keywords
@example
The tag is used to parse a piece of file content and highlight them. Phpdoc will attempt to read the contents of the file from the file path that is marked
@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, and prohibits derivation and modification.
@filesource
Similar to example, except that the tag will directly read the contents of the currently parsed PHP file and display it.
@global
Indicates the global variables referenced in this function
@ingore
Used to ignore the specified keyword in the document
@license
Equivalent to the <A> in the 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
But you can also refer to any one of the keywords in the document by 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 the return point of a method or function
@static
Indicates that the closed word is static.
@var
Indicate variable type
@version
Indicate version information
@todo
Identify areas that should be improved or not implemented
@throws
Indicates an error exception that may be thrown by this function, which is most likely to occur
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, expressed in {@}, specifically include the following:
{@link}
Use the same @link
{@source}
Display the contents of a function or method
6. Some annotation specifications
A. Annotations must be
/**
* XXXXXXX
*/
The form
B. For functions that reference global variables, you must use the glboal tag.
C. For variables, the type must be marked with VAR (int,string,bool ...). ）
D. Functions must indicate their parameters and return values through param and returns tags
E. For the occurrence of two or more than two keywords, to pass Ingore ignored redundant, only one can
F. Where other functions or classes are invoked, link or other tags are linked to the appropriate section to facilitate the reading of documents.
G. Use of non-document annotations where necessary to improve code readability.
H. Descriptive content as concise as possible, using phrases rather than sentences.
I. Global variables, static variables and constants must be indicated with the corresponding markup
7. Summary
Phpdocumentor is a very powerful automated document generation tool that helps us write specification annotations, generate Easy-to-understand, structured documents, and help with our code upgrades, maintenance, and handover.
For more detailed instructions on phpdocumentor, you can go to its official website
http://manual.phpdoc.org/Access
8. Appendix
Appendix 1:
Keywords that can be identified by Phpdoc:
Include
Require
Include_once
Require_once
Define
function
Global
Class
Appendix 2
Labels that can be used in the document
<b>
<code>
<br>
<kdb>
<li>
<pre>
<ul>
<samp>
<var>
Appendix III:
A section of PHP code that contains the specification annotation:
Copy Code code as follows:
<?php
/**
* Sample File 2, Phpdocumentor Quickstart
*
* This file demonstrates the rich information so can is included in
* In-code documentation through Docblocks and tags.
* @author Greg Beaver <[email]cellog@php.net[/email]>
* @version 1.0
* @package Sample
*/
Sample file #1
/**
* Dummy include value, to demonstrate the parsing power of Phpdocumentor
*/
Include_once ' sample3.php ';
/**
* Special global variable Declaration docblock
* @global integer $GLOBALS [' _myvar ']
* @name $_myvar
*/
$GLOBALS [' _myvar '] = 6;
/**
* Constants
*/
/**
* The constant
*/
Define (' testing ', 6);
/**
* Second constant
*/
Define (' Anotherconstant ', strlen (' Hello '));
/**
* A Sample Function DocBlock
* @global String Document The fact this function uses $_myvar
* @staticvar integer $staticvar This is actually what is returned
* @param string $param 1 name to declare
* @param string $param 2 value of the name
* @return Integer
*/
function Firstfunc ($param 1, $param 2 = ' optional ') {
static $staticvar = 7;
Global $_myvar;
return $staticvar;
}
/**
* The example class, this is in the same package as the
* Procedural stuff in the start of the file
* @package Sample
* @subpackage Classes
*/
class MyClass {
/**
* A Sample Private variable, this can is hidden with the--parseprivate
* option
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* @link http://www.example.com Example link
* @see MyClass ()
* @uses testing, Anotherconstant
* @var Array
*/
var $secondvar =
Array
' Stuff ' =>
Array
6,
17,
' Armadillo '
),
Testing => Anotherconstant
);
/**
* constructor sets up {@link $firstvar}
*/
function MyClass () {
$this->firstvar = 7;
}
/**
* Return a thingie based on $paramie
* @param boolean $paramie
* @return Integer|babyclass
*/
function Parentfunc ($paramie) {
if ($paramie) {
return 6;
} else {
return to new Babyclass;
}
}
}
/**
* @package Sample1
*/
Class Babyclass extends MyClass {
/**
* The answer to life, the universe and Everything
* @var Integer
*/
var $secondvar = 42;
/**
* Configuration Values
* @var Array
*/
var $thirdvar;
/**
* Calls Parent constructor, then increments {@link $firstvar}
*/
function Babyclass () {
Parent::myclass ();
$this->firstvar++;
}
/**
* This always returns a MyClass
* @param ignored $paramie
* @return MyClass
*/
function Parentfunc ($paramie) {
return to new MyClass;
}
}
?>
