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.
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 information of the analyzed classes and modules , establish corresponding indexes, generate xml files, and use customized templates to output files in the specified format for the generated xml files.
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 and enter at the command line
pear install PhpDocumentor
b. Manually install the latest version of PhpDocumentor (now 1.4.0) at http://manual.phpdoc.org/ and unzip the content.
3． How to use PhpDocumentor to generate documentation command line:
In the directory where phpDocumentor is located, enter
Php-h
You will get a detailed parameter list, several important parameters of which are as follows:
-f The name of the file to be analyzed, multiple files separated by commas
-d Directory to be analyzed, multiple directories separated by commas
-t storage path of the generated document
-o The output document format, the structure is output format: converter name: template directory.
For example: phpdoc -o HTML:frames:earthli -f test.php -t docs
The web interface is generated in the new phpdoc. In addition to generating documents on the command line, you can also generate documents on the client browser. The specific method is to first place the content of PhpDocumentor in the apache directory so that it can be accessed through the browser. , the following interface will be displayed after access:
Click the files button to select the php files or folders to be processed. You can also ignore the processing of certain files by specifying Files to ignore in this interface.
Then click the output button to select the storage path and format of the generated document.
Finally, click create, and phpdocumentor will automatically start generating documents. The progress and status of the generation will be displayed at the bottom. If successful, it will be displayed.
Total Documentation 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.
4. Add standard comments to php code
PHPDocument generates documents from comments in your source code, so the process of commenting on 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 see 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 text you generate.
3.2 How to write documentation comments:
All documentation comments are a multi-line comment starting with /**, which is called DocBlock in phpDocumentor. DocBlock refers to the help information about a certain keyword written by software developers so that others can know this through it. The specific purpose of keywords and how to use them. PhpDocumentor specifies that a DocBlock contains the following information:
1. Function brief description area
2. Detailed description area
3. Tag
The first line of the documentation comment is the function description area. The text generally briefly explains the function of this class, method or function. The text of the function description will be displayed in the index area in the generated document. The content of the function description area can be ended 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. If possible, you can also Examples of usage, etc. In this section, you should focus on clarifying the general 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 then write the precautions or special information on a specific platform. This information should be enough so that your readers can write corresponding test information, such as boundary conditions, parameter ranges, Breakpoints, etc.
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.
Regarding document marking, please refer to Section 4: Document Marking for details.
Tags such as <b> <code> can also be used in document comments. Please refer to Appendix 2 for details.
The following is an example of a documentation comment
/**
* Function add, implements the addition of two numbers
*
* A simple addition calculation, the function accepts two numbers a and b, and returns their sum c
*
* @param int addend
* @param int summand
* @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, implements the addition of two numbers
Constants is 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 a document tag refers to the keywords or other document tags that the tag can be used to modify.
All documentation tags begin with @ after the * on each line. If the @ mark appears in the middle of a paragraph, the mark will be treated as normal content and ignored.
@access
Scope of use: class, function, var, define, module
This tag is used to indicate the access rights of the keyword: private, public or protected
@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
This tag is used to parse a piece of file content and highlight it. Phpdoc will try to read the file content from the file path given by this tag.
@const
Scope of use: define
Used to indicate the constants defined in php
@final
Scope of use: class, function, var
Indicates that the keyword is a final class, method, or attribute, and is prohibited from being derived or modified.
@filesource
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 variables referenced in this function
@ingore
Used to ignore specified keywords in the document
@license
Equivalent to <a> in the html tag, first is the URL, then the content to be displayed, such as <a href=”http://www.baidu.com”>Baidu</a>
You can write @license http://www.baidu.com Baidu
@link
similar to license
But you can also point to any keyword in the document through link
@name
Specify an alias for the keyword.
@package
Scope of use: 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
Specify the parameters of a function
@return
Specifies the return pointer of a method or function
@static
Indicates that the keyword is static.
@var
Specify variable type
@version
Specify version information
@todo
Indicate areas that should be improved or not implemented
@throws
Indicates 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, using {@ } means, specifically including the following:
{@link }
The usage is the same as @link
{@source }
Display the contents of a function or method
6． Some annotation specifications
a. The comment must be
/**
* XXXXXXX
*/
form
b. For functions that reference global variables, the glboal tag must be used.
c. For variables, their type must be marked with var (int, string, bool...)
d. The function must indicate its parameters and return value through 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, link or other tags should be used to link to the corresponding part to facilitate 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 declared with corresponding tags
7. Summary
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.
For a more detailed description of phpDocumentor, you can go to its official website
http://manual.phpdoc.org/View
8. Appendix Appendix 1:
Keywords recognized by phpdoc:
Include
Require
include_once
require_once
define
function
global
class
Appendix 2
Tags that can be used in documents
<b>
<code>
<br>
<kdb>
<li>
<pre>
<ul>
<samp>
<var>
Appendix 3:
A piece of php code with canonical comments:
<?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver < [email protected] >
* @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
*/
/**
* first constant
*/
define('testing', 6);
/**
* second constant
*/
define('anotherconstant', strlen('hello'));
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
/**
* The first 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 be 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 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 new myclass;
}
}
?>