皆さん、こんにちは。笹亀です。

新年、最初のブログになりました。
2012年も張り切っていきたいと思います。

本日は最近よくお世話になっているPHPDocについて書きたいと思います。
PHPDocとはjavadocを利用したことがあるかたならご存知かと思いますが、APIドキュメントを自動生成する便利なツールです。基本的な出力はHTMLで行い、APIのドキュメントとしてよく利用されるものです。

現在はPHPDocではなく、PHPDocumentorとしてPEARパッケージにて提供がされております。インストールもPEARコマンドから簡単にインストールできます。

1. pear install --alldeps phpdocumentor

インストール後はphpdocコマンドが使用可能になります。とりあえずテストにDoctrineをPHPDoc化してみたいと思います。
※下記は自分の環境にての実行となります（phpdocコマンドがある箇所から実行してください

1. sasa-no-MacBook-Pro:Desktop sasa$ /opt/local/bin/phpdoc -t ./doctest/doc  -d ./doctest/Doctrine/ -o HTML:Smarty:PHP
2.  -t: DOCの出力先
3.  -d:DOCにする対象フォルダ
4.  -o:出力形式の指定

コマンド実行中にWaringとか結構でたりしますが、うまいことそれなりに作成をしてくれます。


ただ、個人的にデフォルトのものだとデザインがいけてないです。そこでデザインにもこだわりたいというあなたへPHPDocumentorはSmartyを利用しているので、出力するテンプレートを簡単に切り替えができます。
下記に綺麗なデザインのテンプレートを作成したものがございます。
http://www.onigoetz.ch/2010/09/11/new-theme-for-phpdocumentor/

ダウンロードからテンプレートを落とし、ダウンロードしたファイルを適当な箇所で解凍します。
解凍したファイルを下記のPHPDocmentorが格納されている箇所にコピーします。

1. sasa-no-MacBook-Pro:~ sasa$ ls -al /opt/local/lib/php/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/Evolve/
2. HTMLSmartyEvolveConverter.inc  templates/ 
4. sasa-no-MacBook-Pro:~ sasa$ ls -al /opt/local/lib/php/data/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/Evolve/
5. HTMLSmartyEvolveConverter.inc  templates/

設置作業が完了しましたら、設置したテンプレートにてDoctrineをPHPDoc化してみたいと思います。
※下記は自分の環境にての実行となります（phpdocコマンドがある箇所から実行してください

1. sasa-no-MacBook-Pro:Desktop sasa$ /opt/local/bin/phpdoc -t ./doctest/docEvolve  -d ./doctest/Doctrine/ -o HTML:Smarty/Evolve:default -s on

下記のようにデザインが綺麗なものでPHPDocとして出力されます。デザインにもこだわったPHPDocを出力することで一歩先のクオリティを目指すこともできますｗ


--------------------------補足情報
PHPDocumentorにて日本語を出力する場合は、文字化け問題にぶつかると思います。
HTML化する際にSmartyのテンプレートを使用しておりまして、テンプレートに直書きで「charset=iso-8859-1」などと記載されております。
下記の箇所にデフォルトのテンプレートが格納されており、ここに入っているheader.tplで指定されている文字コードを変更するとデフォルトの出力する際の文字コードを変更できます。

1. ※自分の環境の場合
2. /opt/local/lib/php/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates/
3.  PEARが入っている箇所のdataフォルダ以下に格納されています
4.  ☓/opt/local/lib/php/PhpDocumentor/phpDocumentor/（こっちには格納されてません
6. 下記のサイトが参考になるかと思います
7.  http://wikiwiki.jp/yonkoushi2/?PHP%2Fphpdocumentor%A4%CB%A4%C4%A4%A4%A4%C6

自分で書き換えるのが面倒って方はバッチをつくっている方もいらっしゃるようで、下記サイトを参考に行うのもありだと思います。
http://hiluckyman.blogspot.com/2010/09/phpdocumentor-utf-8.html

設定や文字コードの調整が大変ですが、1度設定をしてしまえば今後も同じように使用することができますので、
PHPDocumentorで自分のAPIを開発者にAPIドキュメントとして提供をしてみてはいかがでしょうか。

下記のサイト様の情報を参考にさせていただきました。
この場をお借り致しまして、お礼を申し上げさせていただきます。ありがとうございました。
http://hiluckyman.blogspot.com/2010/09/phpdocumentor-utf-8.html
http://wikiwiki.jp/yonkoushi2/?PHP%2Fphpdocumentor%A4%CB%A4%C4%A4%A4%A4%C6