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 the tag to indicate access permissions for the keyword: private, public, or proteced use: class,function,var,define,module
@author indicate the author
@copyright Specify copyright information
@const scope of Use: Define used to indicate define constants in PHP
@final scope of Use: Class,function,var indicates that the keyword is a final class, method, property, prohibit derivation, modification.
@global indicate the global variables referenced in this function
@name Specify an alias for the keyword.
@package is used to logically group one or several keywords into a set.
@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 off-build word is static.
@var indicate the variable type
@version Specifying version information
@todo indicate areas that should be improved or not implemented
@link can refer to any one of the keywords in the document via link
@ingore used to omit the specified keyword from the document
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. Where necessary use non-document annotations (Phpdoc comments before the unrecognized keyword) 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
Keywords that can be identified by Phpdoc:
Include
Require
Include_once
Require_once
Define
function
Global
Class
3. The PHP code for the specification comment:
<?php
/**
* File name (sample2.php)
*
* Function description (slightly)
*
* @author Steve <[email protected]>
* @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 (if the parent class is added)
*/
class MyClass {
/**
* Declare common variables
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* Create constructor {@link $firstvar}
*/
function MyClass () {
$this->firstvar = 7;
}
/**
* Define Functions
*
* Function Function description
*
* @global String $_myvar
* @staticvar integer $staticvar
* @param string $param 1
* @param string $param 2
* @return integer|string
*/
function Firstfunc ($param 1, $param 2 = ' optional ') {
static $staticvar = 7;
Global $_myvar;
return $staticvar;
}
}
?>
How to write PHP specification comments
