LUNARAVE WEBクリエイターの仕事と休息

アクセスカウンタ

Google Maps APIの利用戦国IXAWeb技術Youtubeチャンネル

zoom RSS PHPファイルのドキュメント自動生成 -PhpDocumentor-

<<   作成日時 : 2009/09/02 20:46   >>

驚いた ブログ気持玉 2 / トラックバック 0 / コメント 0

システムを構築すると機能一覧やファイルの構成一覧など仕様書(ドキュメント)を顧客向けや作成者以外のスタッフでも理解できるように社内向けに作成しなければならないのだが、詳細に記載するほどドキュメント作成にかなりの時間が取られるし、変更が入るとさらに手間がかかる。

いくつかシステムを構築していればドキュメントのテンプレートらしきものが出来上がってくるのだが、ドキュメント類の中でも"プログラム"に関するものはファイル数や構成によって大きく変わるので作成には苦労する。

そこで、決まった体裁でコメントを記述して、それが記載されているファイル名とそのコメントを抽出して自動的に別ファイルに保存されるマクロやソフトがないかと考えた。

やはり考えることは皆同じで"PhpDocumentor"というモジュールを使えば実現できることがわかった。

名前の通りPHPファイルに対してドキュメントを自動生成してくれる。


早速使ってみたいところだが、この"PhpDocumentor"はPEARを利用したものでサーバに"PhpDocumentor"がインストールされていないと利用できない。

そのため、
しかし"CPI"などroot権限が無いホスティングサーバでは利用できないが、"ラピッドサイト"のようにVPSでもあればインストールして利用できる。


まずはサーバに"PhpDocumentor"があるか確認する。
以下のコマンドでPEARのどのモジュールがインストールされているかがわかる。

[root@localhost html]# pear list
Installed packages, channel pear.php.net:
=========================================
Package Version State
Archive_Tar 1.3.2 stable
Console_Getopt 1.2.3 stable
PEAR 1.7.2 stable
Structures_Graph 1.0.2 stable



どうも入っていないようなので、インストールする。


[root@localhost init.d]# pear install PhpDocumentor
downloading PhpDocumentor-1.4.2.tgz ...
Starting to download PhpDocumentor-1.4.2.tgz (2,421,028 bytes)
...................(略).............done: 2,421,028 bytes
install ok: channel://pear.php.net/PhpDocumentor-1.4.2



これだけで準備が出来たので、後はPEARコマンドを実行すれば生成される。

その前に、ドキュメント化するPHPファイルに決まった体裁のコメントを記述しておく。

オープンソースのPHPファイルではよく見るコメントの体裁で、今思えば"PhpDocumentor"に対応しているのだと気づく。


/**
* コメントを記述します
*
* @version バージョンを記述
* @author 作者を記述
*
*/



"@"は一種の変数のようなもので、このパターンによってドキュメント生成する場合に定位置に記載される。
この他にもリンクや戻り値などいくつか用意されている。


PHPファイルにコメントを記入したら、実際にドキュメント化を実行する。
コマンドの一例に以下のものがある。


[root@localhost ~]# phpdoc -d [PHPファイルがあるフォルダ] -t [ドキュメント保存するフォルダ]
PHP Version 5.2.8
phpDocumentor version 1.4.2
(略)
Parsing time: 19 seconds
Conversion time: 49 seconds
Total Documentation Time: 68 seconds
done



ドキュメントを保存するフォルダを公開ディレクトリ以下にあれば、ブラウザから確認することができる。

 PhpDocumentor


デザインはPHPマニュアルに似ており、左のリンクメニューをクリックすればコンテンツの遷移が可能だ。

デザインはいくつか用意されていて、もちろん自分で用意したものも利用できる。
例えば以下のようなコマンドでデザインを変更できる。


[root@localhost ~]# phpdoc -o HTML:Smarty:PHP -d [PHPファイルがあるフォルダ] -t [ドキュメント保存するフォルダ]



利用するデザインによっては日本語が文字化けするのだが、"header.tpl"のcharsetを"EUC-JP"や"Shift-JIS"に変更すれば文字化けが解消される。


見ての通りHTMLに書き出されるので、ローカル環境にフォルダごと持ってくれば公開ディレクトリでなくても閲覧できる。
プログラム仕様書なので公開されていると非常に問題でもあるのだが・・・。


しかし、社内向けのドキュメントだと問題ないかもしれないが、顧客に納品する場合は文章形式でないのでこれではダメな場合があるだろう。

そこでこの"PhpDocumentor"にはPDFへの出力も可能で、下記のコマンドでPDFファイルが生成される。


[root@localhost ~]# phpdoc -o PDF:default:default -d [PHPファイルがあるフォルダ] -t [ドキュメント保存するフォルダ]



生成されたPDFは表紙にリンク設定された目次もありドキュメントとして機能している。
残念ながら日本語があると文字化けを起こし、その解消の仕方はまだわからない。

どうもデフォルトで利用しているフォントが"Helvetica"なので全角文字に対応できていないのが原因だと思うが、フォントが"afm"または"pfb"を利用しているようで、日本語フォントを変換してテストしているが未だ日本語表示に成功していない。

日本語表示できればデザインテンプレートで自由に体裁を整えられるし、納品物として十分通用するだろう。


ちなみにドキュメントを作成するだけであれば"VMware"などを使って手元の端末でPEARが実行できる環境を作りコマンドを実行する方法もある。
用意するのは手間だが、生成だけであればPHPがシステムとして動く必要はないので実験も含めて気軽に利用できるかもしれない。

テーマ

注目テーマ 一覧


月別リンク

ブログ気持玉

クリックして気持ちを伝えよう!
ログインしてクリックすれば、自分のブログへのリンクが付きます。
→ログインへ
気持玉数 : 2
驚いた
面白い

トラックバック(0件)

タイトル (本文) ブログ名/日時

トラックバック用URL help


自分のブログにトラックバック記事作成(会員用) help

タイトル
本 文

コメント(0件)

内 容 ニックネーム/日時

コメントする help

ニックネーム
本 文
PHPファイルのドキュメント自動生成 -PhpDocumentor- LUNARAVE WEBクリエイターの仕事と休息/BIGLOBEウェブリブログ
文字サイズ:       閉じる