Javadoc(あるいはDoxygen)のように、PHPにもPHPDocumentorというAPIドキュメントを作ってくれるツールがあります。(DoxygenもPHPに対応しているようですが、PHP界ではこちらのほうがメジャーなようです。)
本稿では、PHPDocumentorをインストールして、実際に利用してみます。
(2014年12月23日追記:Pleiades All in One Eclipse 4.4 Luna PHP fullでのインストールについて追記しました。)
(2015年2月26日追記:インストール方法については「Composerによるツールのインストール」を起稿しました。こちらをご参照下さい。)
はじめに
Eclipse+PDTを使っていると自動的にPHPDoc形式のコメントを生成してくれて便利です。
しかし実際にレポートを生成してみないと、コメントの仕方もわかりません。ということで使ってみました。
Pleiades All in One(XAMPP Version 1.8.1)にてインストールした現在の環境にはPHPDocumentor Version 1.4.4がすでにインストールされているようです。しかし使ってみようとすると、「phpDocumentor.iniがないよ」と怒られてしまいます。
そこでPHPDocumentor2をインストールすることにしました。(PHPUnitの件もありましたので、XAMPPに入っているPEARのパッケージは疑ったほうが良いかもしれません。)
尚、本稿は以下の環境をもとに記載しております。
- Windows7 64bit
- PHP 5.4.7 (VC9 X86 32bit thread safe) +PEAR : C:\pleiades\xampp\php\php.exe
記事中のパス等は各位の環境に合わせて、読み替えをお願いします。
(2014年12月23日追記:Windows 8.1 64bit+PHP 5.4.19でインストールを確認しました。)
インストールするオープンソース・ソフトウェア
(2014年12月23日追記:Graphvizを追記して章立てを変更しました。)
Graphviz
クラス図などを描画して画像ファイルを作成するソフトウェアです。
インストール方法は詳説しませんが、Windowsのダウンロードページより、パッケージ(.msi)を選択してダウンロードし、実行してインストーラーに従います。(2014年12月3日現在、最新の安定版はgraphviz-2.38.msiでした。)
そして環境変数PATHに「C:\Program Files (x86)\Graphviz2.38\bin」を追加しておきます。(32bitの場合は(x86)がなかったり、Graphvizの後の数字が違うと思いますので、各位の環境にあわせて読み替えて下さい。)
Windows8.1の場合、環境変数の設定は以下のようになります。
- コントとロールパネルのシステムを開く。(Windowsキー+X→Y)
- 左の「システムの詳細設定」をクリックして「システムのプロパティ」を開く。
- 環境設定タブより「環境変数」をクリックしてダイアログを開く。
- 「システム環境変数」より「Path」をダブルクリックする。
- 「変数値」の最後尾に”;”に続いてパスを追加する。
PHPDocumentor
PHPDocumentorのサイトはこちらです。
本稿ではPHPDocumentor Version 2.1.0をレビューします。
(2014年12月23日追記:Version 2.8.1でインストールを確認しました。)
PHPDocumentorのインストール
<2015年2月26日追記:Composerによるインストール>
新しく「Composerによるツールのインストール」を起稿しました。
現在のところ以下のPearによるインストールも有効ですが、PHPMDなどと合わせて使う場合はComposerでまとめてインストールしたほうが簡単です。
</2015年2月26日追記>
PHPDocumentorのインストールは、コマンドプロンプトより以下のように入力します。
(2014年12月23日追記:Windows 8.1では、管理者モードのコマンドプロンプト(Windowsキー+X→A)にて入力します。また現在のver.2.8.1では、アーカイブが巨大なせいかダウンロードした後(done:の表示の後)に長ーい間表示が更新されず、不安になります。かなり長ーい間(数時間)、放置が必要です。)
C:\Users\user>cd C:\pleiades\xampp\php C:\pleiades\xampp\php>pear.bat channel-discover pear.phpdoc.org C:\pleiades\xampp\php>pear.bat uninstall phpdoc/phpDocumentor C:\pleiades\xampp\php>pear.bat install phpdoc/phpDocumentor
新規にインストールする場合は3行は必要ありません。
そして確認します。
C:\pleiades\xampp\php>php phpdoc.php --version phpDocumentor version 2.1.0
無事、PHPDocumentor Version 2.1.0がインストールできました。
PHPDocumentorの試用
PHPDocumentorを使ってみます。プロジェクトルートに移動して、以下のコマンドを入力します。
C:\pleiades\xampp\php\php.exe C:\pleiades\xampp\php\phpdoc.php -d src -t docs\api
srcがソースのディレクトリ、docs\apiがドキュメントを生成するディレクトリになります。
-t オプションで指定したディレクトリにHTMLファイルが生成されます。
<2015年2月26日追記>
先のComposerにてインストールした場合は以下の様な入力になります。
C:\pleiades\xampp\php\vender\bin\phpdoc.bat -d src -t docs\api
(php.exeにパスが通っている必要があります。)
</2015年2月26日追記>
ドキュメントのギャラリー
本章では、PHPDocumentorによって生成されたページのキャプチャを展示します。
ネームスペースごとの表示
ネームスペースに含まれるクラス、関数などが表示されます。
左の階層メニューからネームスペース、クラスが選択できます。ネームスペースの’>’をクリックすることで子供が展開されます。
クラス
クラスのトップページです。
行に可視性(public、protected、private)、列にメソッド、プロパティ、定数が配置された表形式になります。名前はリンクになっています。
継承している親クラスのメンバも展開されるので、親クラスに遡る必要もありません。
メソッド
メソッドや関数はこのように表示されます。左肩のアイコンは可視性を表します。
返り値がいまいちですねえ。doxygenの@retvalのように複数種類分けて書ければ良いのですが。
プロパティ
プロパティはこんなかんじです。
クラスの階層図
上部右メニューのChartsからClass hierarchy diagramを選択すると、継承関係とネームスペースが表された階層図が表示されます。
エラー表示
上部右メニューのReportsからErrorsを選択すると、phpdocコメントのエラーが表示されます。
これも修正しないといけませんね。(ファイルのサマリーなんて書いていないし…)
まとめ
PHPDocumentorをインストールし、使ってみました。
昔のJavadocやDoxygenと較べても使いやすいインタフェイスだと思います。
一点、「</>」というボタン、恐らくソースの該当部分を表示する機能だと思うのですが、クリックしてもエラーが表示されます。
Pingback: eclipse phpdoc エラー | eclipseブログ