PHPDocumentor アノテーション仕様の構成-php手册-php.cn

コメントを書いてもらえますか？この問題は、コードを書き始めたときから私を悩ませてきましたが、他の学生も悩ませていると思います。以前は、コメントを書くための有効な標準がなく、最近まで phpdocumentor のコメント標準を読んでいました。そのため、メンテナンスや共同開発に多大な問題が生じていました。

phpdocumentor のコメント基準を以下にまとめます。

タイプ (データ型):

string 文字列型
整数または int 整数
boolean または bool ブール型 true または false
float または double 浮動小数点型
オブジェクトオブジェクト
混合混合型は、型が指定されていないか、型が不明な場合に使用されます
配列配列
resource リソースタイプ (データベースクエリによって返されるものなど)
void null 値 (コントローラーの戻り値がよく使用されます)
null null 型
呼び出し可能なコールバック関数
false または true true または fasle のみが返される場合は、

自分自身

タグ:

テーブル>

例:

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

@api

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

ログイン後にコピー

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

@作者

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

ログイン後にコピー

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

@カテゴリー

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

ログイン後にコピー

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

@copyright

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

ログイン後にコピー

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

@非推奨

/**
  * @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 はサポートされていません

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

@無視

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

ログイン後にコピー

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

@内部

 /**
  * @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 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()
 {
     <...>
 }

ログイン後にコピー

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

@メソッド

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

ログイン後にコピー

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

@パッケージ

/**
  * @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)
 {
     <...>
 }

ログイン後にコピー

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

@プロパティ

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 stringnull The label&#39;s text or null if none provided.
  */
 function getLabel()
 {
     <...>
 }

ログイン後にコピー

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

@参照

 /**
  * @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) {
         <...>
     }
 }

ログイン後にコピー

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

@サブパッケージ

/**
  * @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 MyClass::$items to retrieve the count from.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

ログイン後にコピー

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

@var

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

ログイン後にコピー

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

@バージョン

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

ログイン後にコピー

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

ログイン後にコピー

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	版本

タグ