PHP プログラム仕様書を作成 PHP Documentor

PHP

PHPプログラムの仕様書を自動的に作成してくれる、PHP　Documentorの紹介です。
WebサーバーとPHPがあれば、Webインターフェースからさくさく作れますよ。

①インストール
まずは、下記の本家のサイトへアクセスし、右上のダウンロードをクリックしてプログラムをダウンロードします。

http://www.phpdoc.org/

ダウンロードした圧縮ファイルを解凍して、Webサーバーでアクセスできる箇所においてください。
あとは、PHP Documentorを置いたディレクトリにアクセスすれば、PHP Documentorの画面が見られるはずです。

②仕様書の作成

上部にあるメニューのFilesというところをクリックしましょう。
Files to parse はファイル単位で仕様書を作成したいファイルをパスを含めて記述します。
ディレクトリ単位で仕様書を作成したいファイルがある場合は、
Directory to parse にディレクトリをパスを含めて記述しましょう。

次に、上部のメニューからOutputをクリックします。
ここでは、仕様書を作成して出力するディレクトリの指定と、形式を指定します。
Targetというボックスに出力先のディレクトリを、Output Formatに、どの形式で出力したいかを記述します。
プルダウンメニューから選択できるようになっているので、プルダウンから選び、“Add the converter in the help box”というリンクをクリックすると、上のボックスにコピーしてくれます。

これで、右下の「create」ボタンをクリックすれば、レポートの出力開始です！

③文字化け対策

…ですが、このままだと日本語が文字化けしてしまいます。&cry;
理由は、出力のテンプレートファイルのいたるところに「encoding=”iso-8859-1″」と書いてあるから･･･。
テンプレートファイルは /phpdocs/phpDocumentor/Converters/HTML/frames/templates などに入ってますが、数が多いので、「encoding=”iso-8859-1″」を何かツールで一括置換しちゃった方が早いです。
ちなみに、②で選択する出力形式が、ここでディレクトリの名前になってついているので、一括置換しないで、一つの出力形式のみ修正する方法もありだと思います。

下記のサイトを参考にさせて頂きました。m(_ _)m
http://phpspot.net/php/pgphpDocumentor%82%BB%82%CC%82Q.html

④文字化け対策2

しかし、それだけだとIE6では文字化けしてしまいました。
文字コードを明示的に指定してあげる必要があります。
各テンプレートファイルの”header.tpl”に～の間に

 <meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />

などと文字コードを指定してあげると治ります。

⑤ソースコードの記述

ソースコードに、下記のような記述でコメントがしてあれば、PHP Documentorが拾ってくれます。

 /**
 *コメントテストだよー　
 */

他に、上記のようなコメントの中に@ で始まる記述を入れておくと、それも拾ってくれます。

 /**
 *コメントテストだよー　
 *@author テスト
 *@version 1.1
 */

たくさんあるので、下記のマニュアルサイトにあるものを見てくださいね。

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html