PHPのドキュメンテーションツールはApiGenがいい感じなんじゃないか
guzzleで使われていたApiGenが良さそうだったので、試してみた。これはイイ!php-coverallsのAPI docを試しに作ってGitHub Pagesに載せてみた。
Which one is better?
PHPでは、他にも使えるツールがいくつかある。PHP用のツールとしては、以下が有名どころなんじゃないかと思う。括弧内の数字はGitHubでのスターの数。
ツール | composer | PHP |
---|---|---|
phpDocumentor2 GitHub (823) |
○ | 5.3.3+ |
ApiGen GitHub (362) |
○ | 5.3.0+ |
phpDox GitHub (140) |
× | 5.3.3+ |
PHPDoctor GitHub (89) |
○ | 5.2.0+ |
GitHubのスターの数はphpDocumentor2が一番多い。PEARのAPI docでも使われているphpDocumentorの後継ツールだ。しかし、以前試した時には、Page level docを要求しておきながら、どこに書いてもエラーになったりと、中々安定しない印象だった。生成速度はv1と比べてだいぶ速い。
phpDoxはTemplate for Jenkins Jobs for PHP Projectsでも採用されているツールだ。ファイル判定がFILEINFO_MIME
のため、.php
のファイルであってもC++のファイルだと勘違いされることが多々あった。この部分だけ修正すれば使えないこともないが、@inheritdoc
に対応していないので、eclipseでPDTを使っている自分としてはあまりメリットがない。さらにPackagistに登録されていないため、composer install
しようとすると、PEARのめんどくさい書き方をしなければいけないのが(ry
PHPDoctorは、以前にもphpDocumentorの乗り換え先を検討したときに使用してみたが、ドキュメントの生成が中々速くていい感じだった。最近になって、composerに対応したようだ。
ApiGen
- PHP 5.3+
- composer対応!
@inheritdoc
対応!- まさかのGoogle Analytics対応
完璧じゃないか。guzzleのAPI docを見た感じだと、デフォルトのテンプレートで十分読みやすそうだ。
Good
試してみて分かった良いところ。
- 生成速度はphpDocumentor2と同程度
- checkstyle形式でエラー一覧を出力可能
- vendorライブラリを読み込みつつも、メインプロジェクトを設定可能
php-coverallsで試してみたところ、phpDocumentor2とApiGen 2.8.0は25秒前後で完了した。
個人的に一番良かったのは、3番目。他のツールが対応していない部分だ。
例えば、メインプロジェクトのクラス(My\FooApplication
)が、依存ライブラリのクラス(Vendor\Application
)を継承していたとする。この場合、Vendor
以下のクラスも生成対象に含めてしまうと、API docのトップページにはMy
もVendor
も一覧表示されてしまう。My
を含めない場合、@inheritdoc
の参照先が無くなってしまい、ドキュメントに反映されない。しかし、依存ライブラリに関するドキュメントではないので、一覧にはメインプロジェクトだけを載せたい。
そんな時に、--main
オプションに名前空間の先頭を指定しておくと、index.html
にはこの名前空間に含まれるクラスだけが一覧表示される。この例だと、My
をしておくとVendor
以下のクラスは一覧表示されない。さらに、依存ライブラリについてはサイドバーから参照可能になっている。My
以下のクラスとVendor
以下のクラスはここでまとめて参照可能だ。
Configuration by NEON format
ApiGenの設定ファイルはNEONフォーマットになっている。
コマンドオプションの名前がそのまま設定ファイルのキーになるようだが、ハイフンが入っているオプション名の場合、エラーとなってしまった。設定ファイルにどう書いたらいいのだろうか。もちろんコマンドオプションに指定すると大丈夫だった。
Markdown in doc block
phpDocumentor2、phpdoxではdoc block内でmarkdownが出来たりする。ApiGenはまだあまり対応してなさそうだ。コード例なんかが書いてあるdoc blockだと、一行にまとまって出力されてしまった。*でリストを表現している場合はうまく解釈された。
例えばこんなの。
この場合、ApiGenだと、$t = new Test; $t->hello(); // => "hello"
と一行になってしまう。
リストはうまく解釈できて、これはul>li
で出力される。
Conclusion
- ApiGenいいよ!
post commitとかで自動的にAPI docを更新できると便利だと思うんだけど、どうしよう。いまいち、gh-pagesブランチの運用方法が分からない。もう少し調べておきたい。
PSR-?
ツール毎にタグの対応状況が異なっているが、元になっているのは、おそらくphpDocumentorで対応していたタグなんじゃないだろうか。PHPDoc referenceを見ると、phpDocumentor2でも、ほとんど対応されているんじゃないかと思う。PSRでも標準化して欲しいなーと思ったりした。IDE側の対応もしやすくなるだろうし、アノテーションとして利用しているフレームワークやライブラリもあるわけだし。PackagistでもAPI doc見れると便利だと思うんだけど。
アノテーションパーサーもC extensionで作ってるのないのかなーと思って探してみると、Phalconのannotationsがそれらしいのを作ってた。
PSR-FIG mailing list
PHP-FIGのメーリングリストを見てみたら、PHPDocの仕様について、昨年の9月から12月まで、議論されていたらしい。
全てのコメントを追いきれていないため、現在のステータスがよく分からないが、このディスカッションの中では、phpDocumentorのMike van Rielがドラフトを作っていた。
@var
はdeprecatedで、代わりに@type
を使えと書いてあるが、phpDocumentorもApiGenも対応してないし、eclipseも対応していない。どうなるんだろうか。他には、@category
や@subpackage
がdeprecatedになっているようだ。fluent APIの実装が増えてきたことを反映してか、戻り値のself
タイプについても言及されている。
また、メーリングリストの中でdoc blockのタグについて、いくつか議論されていた。