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/

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