phpdocumentorの書き方

コメントからドキュメント生成

phpdocumentorとは

phpdocumentorとは、スクリプトに一定の形式に準拠してコメントを書くと、コメントからマニュアル生成するプログラムです。

コメントの形式は以下のようになります。

/**
 * __construct 簡単な解説
 * 
 * 詳細な解説1 
 * 詳細な解説2 
 * 
 * @access public
 * @return void
 */

コメントの最初に一行で簡単な解説を書きます。 続けて、長めのコメントを書きます。 さらに、タグ(@で始まる) を利用して、利用されている変数、戻り値等を示します。

良く利用するタグ

phpdocumentor で利用頻度が高いと思われるタグをいくつか紹介します。

@access
アクセス権限(private protected public)
@deprecated
古い(使うべきではない)
@final
オーバーライドできない
@link
ハイパーリンク(URL)
@param
パラメータ: データ型、パラメータ名、説明
@return
戻り値: データ型、説明
@see
別要素へのリンク
@todo
実装予定等
@uses
参照している要素への相互リンク
@var
変数: データ型、説明

phpdocumentorのインストール

phpDocumentor からダウンロードします。 解凍してから、phpdoc に実行権限を付与します(chmod コマンド等を利用してください)。 これでコマンドラインから実行できるはずです。

PEAR を利用してインストールすることも可能です。 PEAR を使っている場合はこちらが便利でしょう。

pear install PhpDocumentor

phpdocumentorの使い方

コマンドラインから、以下のように入力します。 srcdir は PHP スクリプトのあるディレクトリです。 targetdir は phpdocumentor が生成したファイルを格納するディレクトリです。(ディレクトリ名は、お使いの環境に合わせて適宜変更してください。)

phpdoc -d ./srcdir/ -t /targetdir/

この他にもオプション引数が設定できます。詳細はphpDocumentor Documentation をごらんください。

phpdocumentor作成例

RSS取得ショートコード(ワードプレスプラグイン)に適用した例rssget.php をごらんください。

Copyright (C) 2003-2013. PHP で WEB 作成 All rights reserved.