【PhpDoc】コメントの書き方のまとめ

関数/メソッドの場合

例文
/**
* aaaの説明
*
* @param string $arg 第一引数
* @param integer $arg2 第二引数
* @return array 戻り値の説明
*/
function aaa($arg,$arg2){}

string
integer
object(オブジェクト)
array
mixed(いろんな型が返る場合),
resource(リソース型)

変数/define定数

/**
* 説明
* @see 関連関数
*/
のように書きます。

クラスの場合

/**
* クラスの説明
*
* @package パッケージ名:ここは、自分でうまく分類作れれば見やすくなる
* @author 作った人
* @since PHP 5.3 PHPのバージョンとかいれときます?
* @version 1.0.1
*/

DocBlockとは?

DocBlockとは、↓の部分のことを言い、
/**
* 関数aaaの説明文
*/
function aaa()
{

phpDocumentorの書き方:記述基本ルール

DocBlockの記述ルールに従う

DocBlockは、/** から始める
全てのコメント行の初めに”*”を入れているもののみ解析する:*で始まらないコメント行は無視。
コメントしたい定義のすぐ上に記載したものが解析される

Short DescriptionLong Description

Short Description

DocBlockの最初のラインから始まり、空白行またはピリオドで終わります。
ピリオドが含まれる単語(example.com や 0.1%のような)の後ろは無視されます。
3行以上になる場合は、最初の1行だけが有効になります。
HTML タグを含ませる事もできます。(記述可能なタグ)

Long Description

「長い説明文」は複数の行を書くことが出来ます。
HTML タグを含ませる事もできます

タグの中で使用頻度が高いタグ

@access

アクセス権限(private protected public)
private:phpDocに載らない
public:phpDocに載る
protected:不明
省略時はpublic

/**
* function funcA, access
* @access private ←phpDocには非表示
*/
function funcA(){ … }

@deprecated

古いもので、互換性のために残しているということを示す

@final

オーバーライドできない

@link

ハイパーリンク(URL)
/**
* 参考サイト http://blog.flavacube.com
* @link http://blog.flavacube.com
*/
define(“flavacube”,1);

@param

関数の引数
パラメータ: データ型、パラメータ名、説明
/**
* テスト関数
* @param bool $aaa 〇〇な値
* @return bool trueかfalseを返す
*/
function function1($aaa)
{
if($aaa)
{
return $aaa;
}
}

@return

関数の戻値
戻り値: データ型、説明

@see

別要素へのリンク

@todo

TODO,開発予定などを記載

@uses

参照している要素への相互リンク

@var

変数: データ型、説明

@author

作者を記述するタグ。
使用可能な関数
global variable, include, constant, function, define, class, variable, method ,page
< >で括られた場所はメールアドレスとして解釈されます。
/**
* @author Joe Shmoe <foo@bar.org>
*/

@copyright

copyrightの定義を行う
使用可能な関数
global variable, include, constant, function, define, class, variable, method, page

/**
* @copyright Copyright © 2010, flavacube.com
*/

@example

サンプルファイル
リンクしたいファイルを指定しておく。ハイライトで表示される。
/**
* @example ./sample.php 関数使用例
*/

@see

参照先を生成できる。
参照先が存在する場合はリンクが生成!
/**
* @see sample
*/
function sample2{ }
/**
* smple2の参考メソッド
*/
function sample{ }

@since

PHP5.0などバージョンを記載しておきますかね。

@version

自分たちで自由にバージョン定義しよう