PHPのAPI DOC生成にDoxygenも使うことにした
経緯
- 以前から一部のリポジトリで phpdoc がメモリ不足で落ちて困っていた
- Doxygen は何年か前にも試していたが、PHP の解釈がイマイチで採用を見送っていた
- 今回試してやはりイマイチだったが、いくつかの問題を我慢すれば使えそうだったので、メモリ不足で落ちるよりマシと判断して使い始めた
現在稼働しているバージョンは 1.5.6
動かせるようになるまで
最初は
- 落ちる
- 返ってこない
ファイルが後を絶たなかった。どうしたか。
EXCLUDE しまくる
まずはこれが基本。設定ファイルの中に EXCLUDE, EXCLUDE_PATTERNS の設定があるのでこれを利用してひたすら問題になるファイルを除外しまくる。話はそれから。
- とりあえず EXCLUDE
- 一つずつコメントやコードの構造を直して落ちないか試す
以上をくり返すことでほとんどのコードを扱えるようになる。
※ Warning はとりあえず無視しして徐々に対応していく。
やばげなパターン
if () {
...
}
でコード全体を囲んでいると doxygen が返ってこなくなりやすいみたい。
とは言え必ず返ってこないかというとそうではなく、コメントの書き方が正しくない場合に返ってこなくなる可能性が高い、という感じらしい。
コメントの書き方ミスにはとても厳しい
phpdoc と違ってかなり厳しい。少なくとも phpdoc 的には大きな問題でなくても Doxygen ではダメなケースは多い。ただし本当に問題になるのはやはり
正しくないコメント
なので、普段からちゃんと書けている場合はとりあえず移行そのものはそれほど大変ではないと思う。
対応してるタグは少ない
phpdoc に比べると対応するタグがだいぶ少ない。ただし、
- シンプルでよいと思うことにする
- ソースにリンクを張れるのである程度解釈が変でも直接読ませることでよしとする
で、乗り越えられる :-)
切り替えて使う
で述べたように phpdoc の生成は自動化しているのだが、この中でドキュメント出力先は都度クリアしてから作業を始めている。このとき削除には
rm -r *
を使っているので、ドキュメント生成先に .doxyfile というファイルが用意されていたら doxygen で、そうでなければ従来通り phpdoc で処理することにした。1
これで、全リポジトリで一気に Doxygen 対応をはかる必要がない。
よさげな設定
いろいろ試行錯誤した結果と default の diff を出してみた。たぶん Java っぽく振るのがいいんだと思ってるんだけど、どうなんだろう。
結果
- Doxygen の PHP 対応は今もやはりイマイチ
- メモリ不足で API DOC を生成できないリポジトリがなくなった
- API DOC 生成のスピードは10倍以上に跳ね上がった
- API DOC 生成に使っているサーバの仕事を増やせる
- Windows 版もあるので、気軽に何回もドキュメント生成を試すことができる
- ドキュメントの品質向上に繋がるかも
いちばん上の階層のドットファイルは rm -r * では削除されない。 ↩