PHP parameter Annotation

Introduction: This is a detailed page for PHP parameter comments. It introduces the related knowledge, skills, experience, and some PHP source code.

Class = 'pingjiaf' frameborder = '0' src = 'HTTP: // biancheng.dnbc?info/pingjia.php? Id = 340853 'rolling = 'no'>

All document comments are a multi-line comments starting with/**. In phpdocumentor, docblock refers to the help information written by software developers about a keyword, this allows others to know the specific purpose of this keyword and how to use it. Phpdocumentor specifies that a docblock contains the following information:
1. Function overview Area
2. Detailed description area
3. Tag
The first line of document comments is the function description area. The body is generally a concise description of the functions of this class, method, or function, the body of the function description is displayed in the index area in the generated document. The content in the function description area can end with a blank line or.
There is a blank line behind the function description area, followed by a detailed description area. This section mainly describes the functions and usage of your API. If possible, it can also be used as an example. In this section, you should focus on the common usage and usage of your API functions or methods, and specify whether it is cross-platform (if involved). For platform-related information, you need to treat it differently from general information. The common practice is to set up another line, and then write the precautions or special information on a specific platform. This information should be sufficient, this allows your readers to write test information, such as boundary conditions, parameter ranges, and breakpoints.
It is also a blank line, followed by the tag of the document, indicating some technical information, mainly the call parameter type, the return value is extremely type, inheritance relationship, related methods/functions.
For more information about document tagging, see Section 4: Document tagging.
For more information, see appendix 2.
Below is an example of document comment

/**
* Add the function to add two numbers.
*
* In a simple addition calculation, the function accepts two numbers A and B and Returns their and C
*
* @ Param int Addition
* @ Param int add count
* @ 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 to add two numbers
Constants is a simple addition calculation. The function accepts two numbers A and B and Returns their and C
Parameters
• Int $ A-addend
• Int $ B-Number of added parts
5. Document Tag:
The scope of use of a document tag is a keyword that can be used to modify a document tag, or other document tag.
All document tags start with @ after each line. If @ is marked in the middle of a passage, the mark will be ignored as common content.
@ Access
Usage scope: Class, function, VAR, define, Module
Indicates the access permission for a keyword: private, public, or proteced.
@ Author
Specify author
@ Copyright
Usage scope: Class, function, VAR, Defi

Scope of use: Define
Used to specify the define constant in PHP
@ Final
Usage scope: Class, function, VAR
Specifies that a keyword is a final class, method, or attribute, and cannot be derived or modified.
@ Filesource
Similar to example, however, this tag will directly read and display the content of the currently resolved PHP file.
@ Global
Specifies the global variables referenced in this function.
@ Ingore
Used to ignore specified keywords in the document
@ License
It is equivalent to <A> in an 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
However, you can refer to any keyword in the document through link.
@ Name
Specify an alias for the keyword.
@ Package
Scope of use: page-> define, function, include
Class-> class, VAR, Methods
It is used to logically group one or more keywords into one group.
@ Shortcut
Indicates that the current class is an abstract class.
@ Param
Specify the parameters of a function.
@ Return
Specifies the return value of a method or function.
@ Static
Indicates that the word is static.
@ VaR
Variable type
@ Version
Specify version information
@ Todo
Specify the areas to be improved or not implemented
@ Throws
Indicates the error exception that this function may throw.
As mentioned above, the mark of common documents must start with @ at the beginning of each line. In addition, there is also a Mark called inline tag, which is represented by {@}, including the following:
{@ Link}
Usage: @ Link
{@ Source}
Display the content of a function or Method
6. Some annotation specifications
A. The comment must be
/**
* Xxxxxxx
*/
Format
B. The glboal mark must be used for functions that reference global variables.
C. For variables, you must use VaR to mark their types (INT, String, bool ...)
D. The function must specify its parameters and return values through PARAM and return tags.
E. For keywords that appear twice or more times, ignore unnecessary keywords through ingore and retain only one keyword.
F. When other functions or classes are called, link or other markup should be used to link to the corresponding part for easy reading of the document.
G. Use non-document comments where necessary to improve Code Easy to use.
H. The descriptive content should be as concise as possible and use phrases instead of sentences as much as possible.
I. global variables, static variables and constants must be marked with corresponding descriptions
7. Summary
Phpdocumentor is a very powerful Automatic Document generation tool. It helps us write standard comments, generate easy-to-understand and well-structured documents, and upgrade and maintain our code, the handover and so on are of great help.
For more details about phpdocumentor, visit its official website.
Http://manual.phpdoc.org/check
8. Appendix
Appendix 1:
Keywords that can be recognized by phpdoc:
Include
Require
Include_once
Require_once
Define
Function
Global
Class
Appendix 2
Tags that can be used in the document
<B>
<Code>
<Br>
<KDB>
<Li>
<PRE>
<Ul>
<SAMP>
<Var>
Appendix 3:
A piece of PHP code containing standard comments:

<? PHP/*** sample file 2, php?entor Quickstart ** this file demonstrates the rich information that can be encoded in * In-code documentation through docblocks and tags. * @ author Greg beaver <cellog@php.net> * @ version 1.0 * @ package sample * // sample file #1/*** dummy include value, to demonstrate the parsing power of phpbench entor */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 Declare * @ Param string $ param2 value of the name * @ return integer */function firstfunc ($ param1, $ param2 = 'optional') {/*** 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 lif E, the universe and everything * @ var integer */var $ secondvar = 42;/*** configuration values * @ var array */var $ thirdvar; /*** callparent 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 ;}}?>

Love J2EE follow Java Michael Jackson video station JSON online tools

Http://biancheng.dnbcw.info/php/340853.html pageno: 7.