概要
phpDocumentorとはクラスやメソッドの定義前にブロックコメントを決められた方式で記述していると、APIドキュメントを自動生成することができるツール
今回はそのphpDocumentorで記述する書式についてまとめる
PHPDocの書き方
前提知識
DocCommentの開始は以下のように記述する
※ 開始行のアスタリスクは必ず2つ
/** * @var int */ $num = rand(0, 10);
1行で記述することもできる
/** @var int */ $num = rand(0, 10);
「//」を使ったコメントではDocCommentにはならにことに注意
PHPDocを記述する例
ファイルの先頭
目的など簡潔に記述する
<?php /** * このファイルではPHPDocの説明をします * * @copyright 会社名 All Rights Reserved * @license https://opensource.org/licenses/mit-license.html MIT License * @author 名前 <メールアドレス> * @link 資料 */
クラス
/** * このクラスではXXXを行います * * 1行空けてもう少し詳しく記述することができる * 複数行記述ができて、不要なら省略もできる * * @access アクセスレベル * @author 名前 <メールアドレス> * @copyright 会社名 All Rights Reserved * @category カテゴリー（処理系） * @package パッケージ（MVC） */
メソッド
@paramで関数の引数を記述できる
@returnで関数が返す型を記述できる(int,float,void,arrayなど)
returnが複数の型を返す場合はstring|booleanなどと記述する
/**
* このメソッドはXXを行います
*
* 詳細(略)
*
* @access アクセスレベル
* @param int $id
* @param string $name
* @return boolean ユーザが存在するかどうか
* @link 参考資料のURL
* @see 関連(呼び出したり)する関数
* @throws 可能性のある例外を記述する
* @todo TODO事項
*/
function isExistsUser($id, $name)
{ 関数の中身は省略 }
変数
@varタグは変数の型を明示できるが
メソッドの戻り値の型が不明な場合にのみ記述する方が良い
/** @var string 名前 */ $name;
ドキュメントを自動生成する
実際に作成してみる
// composerで導入するのでcomposerを準備 $ sudo bash -c "curl -sS https://getcomposer.org/installer | php" $ sudo mv composer.phar /usr/local/bin/composer // phpdocumentor導入 $ composer require "phpdocumentor/phpdocumentor:2.*"
既にPHPDoc形式でコメントを記述したPHPファイルがあるとしてphpdocコマンドでHTMLを作成する
$ ./vendor/bin/phpdoc -t output/ -d src/ -t: DOCの出力先 -d:DOCにする対象フォルダ -o:出力形式の指定
出力されたHTML群を表示させると以下のようにドキュメントが作られている
コメントを書く
コメント一覧