PHPDocumentor アノテーション仕様の構成
- WBOYオリジナル
- 2016-06-21 08:47:43972ブラウズ
コメントを書いてもらえますか？この問題は、コードを書き始めたときから私を悩ませてきましたが、他の学生も悩ませていると思います。以前は、コメントを書くための有効な標準がなく、最近まで phpdocumentor のコメント標準を読んでいました。そのため、メンテナンスや共同開発に多大な問題が生じていました。
phpdocumentor のコメント基準を以下にまとめます。
タイプ (データ型):
-
- string 文字列型
- 整数または int 整数
- boolean または bool ブール型 true または false
- float または double 浮動小数点型
- オブジェクト オブジェクト
- 混合混合型は、型が指定されていないか、型が不明な場合に使用されます
- 配列 配列
- resource リソースタイプ (データベースクエリによって返されるものなど)
- void null 値 (コントローラーの戻り値がよく使用されます)
- null null 型
- 呼び出し可能なコールバック関数
- false または true true または fasle のみが返される場合は、 を使用します
- 自分自身
タグ:
タグ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
版本
要素 説明 API メソッド インターフェースを宣言 著者 任意 著者情報 カテゴリー ファイル、クラス 一連の要素をまとめて分類します 著作権 任意 著作権情報 非推奨 任意 宣言要素は非推奨となっており、将来のリリースでは削除される可能性があります 例 任意 例 ファイルソース ファイル ファイルリソース グローバル 変数 セット変数を宣言する 無視 任意 現在の要素を無視します (phpdocumentor がドキュメントを生成するとき) 内部 任意 値を整数として宣言するか、アプリケーションのデフォルト値を整数として設定します ライセンス ファイル、クラス 州ライセンスの種類 リンク 任意 現在の要素に関連するリンクを宣言します メソッド クラス 現在のクラスのどのマジック メソッドを呼び出すことができるかを宣言します パッケージ ファイル、クラス 現在の要素が属するパッケージを宣言します パラメータ メソッド、関数 現在の要素のパラメータを宣言します プロパティ クラス 呼び出し可能なマジック メソッドを持つ現在のクラスのプロパティを宣言します プロパティ読み取り クラス 現在のクラスがプロパティを読み取る必要があるマジック メソッドを宣言します プロパティ書き込み クラス 現在のクラスがプロパティを設定する必要があるマジック メソッドを宣言します 戻る メソッド、関数 戻り値 参照 任意 現在の要素パラメータが他のサイトまたは要素を参照していることを説明します 以来 任意 現在の要素がどのバージョンから始まるかを宣言します ソース ファイルを除く任意 現在の要素のソースコードを表示します サブパッケージ ファイル、クラス 現在の要素をカテゴリ化します 投げる メソッド、関数 現在の要素によってスローされる例外について説明します todo 任意 現在の要素の開発アクティビティについて説明します 使用 任意 関連する要素を参照します var プロパティ 属性を宣言する バージョン 任意 バージョン 例:
// =============================
@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 'Unix' or 'Windows' */ 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'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 * 'array'. * * @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 { <...> }