PHPのAPIドキュメントを生成「Sami」
SamiはPHP製のオープンソース・ソフトウェア（MIT License）です。
システムのドキュメントを生成するタイプのソフトウェアは幾つかありますが、そのコマンドの書き方を忘れてしまったりします。そこで設定ファイル化することで定期的なドキュメントアップデートを可能にするSamiを紹介します。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-20 12.03.58.1369055905.png)
Symfony2のソースコードをドキュメント化したデモです。左にクラス、右は一覧が出ています。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-20 12.04.07.1369055911.png)
適当に選択してみました。メソッドやその詳細が表示されています。返り値もちゃんと出ていて分かりやすいです。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-20 12.04.11.1369055915.png)
メソッドの説明。引数や返り値、説明文も出ています。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-20 12.05.11.1369055919.png)
内容によってはphp.netへのリンクにもなっています。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-20 12.05.20.1369055924.png)
検索はインクリメンタルに行われます。検索結果の一部が太字になります。
Symfony2やTwig、Zend Framework2などのフレームワーク向けの設定が用意されています。後はこれをPHPコマンドで実行すればドキュメントが生成される仕組みです。テーマにも対応しており、見た目を自在に変更できます。その他、バージョン番号のサポートにも対応しており、バージョンごとにディレクトリを分けることもできます。
MOONGIFTはこう見る
フレームワークやライブラリを開発した場合、そのAPIドキュメントは必須と言えます。特にフレームワークなどは使いこなせばこなすほど、APIドキュメントを直接見た方が得られる情報が多くなります。またスクリプト言語では返り値を定義する必要がないので、ドキュメント内ではどういった形式があるのか明記しておかないと安心して利用できないでしょう。
ソースコード中のコメントから生成するタイプのドキュメントは実際のコードとドキュメントが近い場所にあるために大きくずれることがありません。SamiをCronで設定しておいて定期実行させておけば、いつでも最新のドキュメントが見られるのがメリットと言えます（だからといってドキュメントが常に正しい訳ではないのでご注意を）。