Home >Backend Development >PHP Tutorial >PHPDocumentor annotation specification organization_PHP tutorial

PHPDocumentor annotation specification organization_PHP tutorial

WBOYOriginal: 2016-07-13 10:21:28890browse

PHPDocumentor annotation specification organization

Can you write comments? This problem has been bothering me since I started writing code, and I believe it is also bothering other students. In the past, there was no effective standard for writing comments, which caused a lot of trouble for maintenance and collaborative development. Until recently, I read the comment standard of phpdocumentor.

The following summarizes the comment standards of phpdocumentor:

Type (data type):

string string type
integer or int integer
boolean or bool Boolean type true or false
float or double floating point type
object object
mixed mixed type is used when no type is specified or the type is uncertain
array array
resource resource type (such as returned by database query)
void null value (controller return value is often used)
null null type
callable callback function
false or true Use

self self

Tags:

Tag	Element	Description
api	Methods	声明接口
author	Any	作者信息
category	File, Class	将一系列的元素分类在一起
copyright	Any	版权信息
deprecated	Any	声明元素已被弃用,可以在将来的版本中删除
example	Any	示例
filesource	File	文件资源
global	Variable	声明一个全集变量
ignore	Any	忽略当前元素（phpdocumentor 生成文档时）
internal	Any	声明一个值为整形，或者设置一个应用的默认值为整型
license	File, Class	声明许可类型
link	Any	声明一个和当前元素有关的链接
method	Class	声明当前类那些魔术方法可以被调用
package	File, Class	声明当前元素所属的包
param	Method, Function	声明当前元素的一个参数
property	Class	声明当前类有那些魔术方法可以被调用属性
property-read	Class	声明当前类有那些魔术方法可以读取属性
property-write	Class	声明当前类有那些魔术方法可以设置属性
return	Method, Function	返回值
see	Any	说明当前元素参数引用于其他站点或元素
since	Any	声明当前元素始于于哪个版本
source	Any, except File	展示当前元素的源码
subpackage	File, Class	将当期元素分类
throws	Method, Function	说明当前元素抛出的异常
todo	Any	说明当前元素的开发活动
uses	Any	引用一个关联元素
var	Properties	声明属性
version	Any	版本

Tag

Element

Description

api

Methods

Declare interface

author

Any

Author information

category

File, Class

Categories a series of elements together

Any

deprecated

Any

The declaration element is deprecated and may be removed in a future version

example

Any

Example

filesource

File

File Resources

global

Variable

Declare a set variable

ignore

Any

Ignore the current element (when phpdocumentor generates the document)

internal

Any

Declare a value as an integer, or set an application's default value as an integer

license

File, Class

State license type

link

Any

Declare a link related to the current element

method

Class

Declare which magic methods of the current class can be called

package

File, Class

Declare the package to which the current element belongs

param

Method, Function

Declare a parameter of the current element

property

Class

Declare the properties of the current class that have magic methods that can be called

property-read

Class

Declare which magic methods the current class has to read properties

property-write

Class

Declare which magic methods the current class has to set properties

return

Method, Function

Return value

see

Any

Explain that the current element parameters refer to other sites or elements

since

Any

Declares which version the current element starts from

source

Any, except File

Show the source code of the current element

subpackage

File, Class

Category the current elements

throws

Method, Function

Describes the exception thrown by the current element

todo

Any

Describes development activity for the current element

uses

Any

References an associated element

var

Properties

Declare attributes

version

Any

Version

Example（示例）：

// =============================

@api

/**
  * This method will not change until a major release.
  *
  * @api
  *
  * @return void
  */
  function showVersion()
  {
     <...>
  }

// =============================

@author

/**
  * @author My Name
  * @author My Name <my.name@example.com>
  */</my.name@example.com>

// =============================

@category

 /**
  * Page-Level DocBlock
  *
  * @category MyCategory
  * @package  MyPackage
  */

// =============================

@copyright

/**
  * @copyright 1997-2005 The PHP Group
  */

// =============================

@deprecated

/**
  * @deprecated
  * @deprecated 1.0.0
  * @deprecated No longer used by internal code and not recommended.
  * @deprecated 1.0.0 No longer used by internal code and not recommended.
  */
 function count()
 {
     <...>
 }

// =============================

@example

/**
  * @example example1.php Counting in action.
  * @example http://example.com/example2.phps Counting in action by a 3rd party.
  * @example My Own Example.php My counting.
  */
 function count()
 {
     <...>
 }

// =============================

@filesource

/**
  * @filesource
  */

// =============================

@global phpdocumentor2.0不支持

// =============================

@ignore

if ($ostest) {
     /**
      * This define will either be &#39;Unix&#39; or &#39;Windows&#39;
      */
     define(OS,Unix);
 } else {
     /**
      * @ignore
      */
     define(OS,Windows);
 }

// =============================

@internal

 /**
  * @internal
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

 /**
  * Counts the number of Foo.
  *
  * {@internal Silently adds one extra Foo to compensate for lack of Foo }}
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

// =============================

@license

/**
  * @license GPL
  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  */

// =============================

@link

/**
  * @link http://example.com/my/bar Documentation of Foo.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

/**
  * This method counts the occurrences of Foo.
  *
  * When no more Foo ({@link http://example.com/my/bar}) are given this
  * function will add one as there must always be one Foo.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

// =============================

@method

class Parent
 {
     public function __call()
     {
         <...>
     }
 }
 
 /**
  * @method string getString()
  * @method void setInteger(integer $integer)
  * @method setString(integer $integer)
  */
 class Child extends Parent
 {
     <...>
 }

// =============================

@package

/**
  * @package PSRDocumentationAPI
  */

// =============================

@param

/**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $items Array structure to count the elements of.
  *
  * @return int Returns the number of elements.
  */
 function count(array $items)
 {
     <...>
 }

// =============================

@property

class Parent
 {
     public function __get()
     {
         <...>
     }
 }
 
 /**
  * @property string $myProperty
  */
 class Child extends Parent
 {
     <...>
 }

// =============================

@property-read

class Parent
 {
     public function __get()
     {
         <...>
     }
 }
 
 /**
  * @property-read string $myProperty
  */
 class Child extends Parent
 {
     <...>
 }

// =============================

@property-write

 class Parent
 {
     public function __set()
     {
         <...>
     }
 }
 
 /**
  * @property-write string $myProperty
  */
 class Child extends Parent
 {
     <...>
 }

// =============================

@return

/**
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

/**
  * @return string|null The label&#39;s text or null if none provided.
  */
 function getLabel()
 {
     <...>
 }

// =============================

@see

 /**
  * @see http://example.com/my/bar Documentation of Foo.
  * @see MyClass::$items           for the property whose items are counted
  * @see MyClass::setItems()       to set the items for this collection.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

// =============================

@since

/**
  * @since 1.0.1 First time this was introduced.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

 /**
  * @since 1.0.2 Added the $b argument.
  * @since 1.0.1 Added the $a argument.
  * @since 1.0.0
  *
  * @return void
  */
 function dump($a, $b)
 {
     <...>
 }

// =============================

@source

/**
  * @source 2 1 Check that ensures lazy counting.
  */
 function count()
 {
     if (null === $this->count) {
         <...>
     }
 }

// =============================

@subpackage

/**
  * @package PSR
  * @subpackage DocumentationAPI
  */

// =============================

@throws

/**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $array Array structure to count the elements of.
  *
  * @throws InvalidArgumentException if the provided argument is not of type
  *     &#39;array&#39;.
  *
  * @return int Returns the number of elements.
  */
 function count($items)
 {
     <...>
 }

// =============================

@todo

 /**
  * Counts the number of items in the provided array.
  *
  * @todo add an array parameter to count
  *
  * @return int Returns the number of elements.
  */
 function count()
 {
     <...>
 }

// =============================

@uses

/**
  * @uses MyClass::$items to retrieve the count from.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

// =============================

@var

 class Counter
 {
/**
  * @var
  */
public $var;
 }

// =============================

@version

/**
  * @version 1.0.1
  */
 class Counter
 {
     <...>
 }

 /**
  * @version GIT: $Id$ In development. Very unstable.
  */
 class NeoCounter
 {
     <...>
 }

Statement：

The content of this article is voluntarily contributed by netizens, and the copyright belongs to the original author. This site does not assume corresponding legal responsibility. If you find any content suspected of plagiarism or infringement, please contact admin@php.cn

Previous article：PHP method to download files using file streams (attached: solving the problem of garbled downloaded file content), _PHP tutorialNext article：PHP method to download files using file streams (attached: solving the problem of garbled downloaded file content), _PHP tutorial

See more

PHPDocumentor annotation specification organization_PHP tutorial

PHPDocumentor annotation specification organization

The following summarizes the comment standards of phpdocumentor:

Related articles