Home > Article > Backend Development > Summary of PHPDocument code comment specifications_PHP Tutorial
Summary of PHPDocument code comment specifications_PHP Tutorial
- WBOYOriginal
- 2016-07-21 15:03:18688browse
1. Install phpDocumentor (command line installation is not recommended)
Download the latest version of PhpDoc at http://manual.phpdoc.org/
Put it in the web server directory to make it pass The browser can access
click the files button and 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 the document.
2． How to write PHP specification comments
All documentation tags start with @ after * on each line. If the @ mark appears in the middle of a paragraph, the mark will be treated as normal content and ignored.
@access This tag is used to indicate the access permission of keywords: private, public or protected. Scope of use: class, function, var, define, module
@author specifies the author
@copyright specifies copyright information
@const Scope of use: define Used to specify the constant defined in PHP
@final Scope of use: class, function, var Specifies that the keyword is a final class, method, attribute, and prohibits derivation and modification.
@global specifies the global variable referenced in this function
@name specifies an alias for the keyword.
@package is used to logically group 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 value of a method or function
@static indicates that the keyword is static.
@var specifies the variable type
@version specifies the version information
@todo specifies areas that should be improved or not implemented
@link You can point to any keyword in the document through link
@ ingore is used to ignore specified keywords in the document
Some comment specifications
a. Comments must be in the form of
/**
* XXXXXXX
*/
b. For functions that reference global variables, they must Use glboal tag.
c. For variables, their types (int, string, bool...) must be marked with var
d. Functions must indicate their parameters and return values through param and return markers
e. For two occurrences For keywords used twice or more, the redundant ones should be ignored through ingore, and only one should be kept
f. Where other functions or classes are called, link or other tags should be used to link to the corresponding part to facilitate documentation. of reading.
g. Use non-documentation comments (comments before keywords that PHPDOC cannot recognize) 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
Keywords that can be recognized by phpdoc:
Include
Require
include_once
require_once
define
function
global
class
3. Standard annotated php code:
/**
* File name (sample2.php)
*
* Function description (omitted)
*
* @author steve
* @version 1.0
* @package sample2
*/
/**
* Include files
*/
include_once 'sample3.php';
/**
* Declare global variables
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* Declare global constants
*/
define('NUM', 6);
/**
* Class name
*
* Class function description
*
* @package sample2
* @subpackage classes (add if it is a parent class)
*/
class myclass {
/**
* Declare ordinary variables
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* Create constructor {@link $firstvar}
* /
function myclass() {
$this->firstvar = 7;
}
/**
* Define function
*
* Function description
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param1
* @param string $param2
* @return integer|string
*/
function firstFunc($param1, $param2 = 'optional ') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
}
?>