PHPソースからドキュメントを生成する主要な3ツールを試してみました。どのツールもそれほど深くは調べていないのでインストール＋アルファ程度の設定変更で試しています。
環境はCentOS4.4＋PHP5.2.3です。
phpDocumentor
PHPでできたツールです。pearコマンドでインストールできることもあって、PHPのドキュメントジェネレータとして人気があります。
- インストール
pearコマンドでインストールできます。
-
$ pear install --alldeps phpdocumentor
- ドキュメント生成
phpdocコマンドで生成します。とりあえずドキュメントを生成するだけなら設定ファイルの変更は不要です。
-
./src 以下のPHPファイルを対象に ./doc 以下にドキュメントを生成
-
$ phpdoc -t ./doc -d ./src
[参考サイト]
- phpDocumentor: The complete documentation solution for PHP[本家]
- Do You PHP? - phpDocumentor - PHPDocに代わるAPIドキュメント自動生成ツール
Doxygen
C++でできたツールです。DoxygenはC/C++、Javaをはじめ様々な言語についてドキュメントを生成することができます。どちらかと言うと、C/C++、Java、Pythonがメインのツールですが、PHPでも十分なドキュメントを生成することができます。
- インストール
CentOS4用はRPMがあるのでyumコマンドでインストールできます。
-
$ sudo yum install Doxygen
ただRPMは1.3.9ですので、最新版(1.5.3)がよければソースからインストールします。
-
$ tar zxvf doxygen-1.5.3.src.tar.gz
-
$ cd doxygen-1.5.3
-
$ ./configure
-
$ make
-
$ sudo make install
- ドキュメント生成
まず設定ファイルを生成します。-gで生成する設定ファイルのファイル名を指定します。ファイル名を指定しなければDoxyfileという設定ファイルがカレントディレクトリに生成されます。
-
$ doxygen -g [config]
次に設定ファイルを編集します。下記は最低限変更した方が良いと思う項目です。
-
$ vi Doxyfile
-
# ドキュメント出力ディレクトリ（省略すればカレントディレクトリに出力）
-
# => doc ディレクトリに出力
-
#OUTPUT_DIRECTORY =
-
OUTPUT_DIRECTORY = doc
-
-
# ソースディレクトリ（省略すればカレントディレクトリ）
-
# => src ディレクトリ以下のファイルを解析
-
#INPUT =
-
INPUT = src
-
-
# 再帰的にソースディレクトリを解析する
-
# => 再帰する（YESにしないとINPUTで指定したディレクトリのみ解析する）
-
#RECURSIVE = NO
-
RECURSIVE = YES
-
-
# ソースコードページを生成する
-
# => ソースコードページを生成
-
#SOURCE_BROWSER = NO
-
SOURCE_BROWSER = YES
-
-
# ソースコードページにてコメントを削除する
-
# => ソースコードページにコメント出力
-
#STRIP_CODE_COMMENTS = YES
-
STRIP_CODE_COMMENTS = NO
ドキュメント生成コマンドを実行するとドキュメントが生成されます。
-
$ doxygen Doxyfile
[参考サイト]
PHPXRef
Perlでできたツールです。phpDocumentorやDoxygenとは少し毛色が異なり、クラス図などは表示されません。上記2ツールはクラス構造などをドキュメント化しますが、PHPXRefはソースコード自体をドキュメント化するのを目的としています。
- インストール
PHPXref - The PHP Cross Referencing Documentation Utilityから最新版ソース（0.7）をダウンロードして展開するだけでokです。
-
$ tar zxvf phpxref-0.7.tar.gz
-
$ cd phpxref-0.7
- ドキュメント生成
設定ファイルを編集します。展開したディレクトリ内にあるphpxref.cfgが設定ファイルになります。
-
$ vi phpxref.cfg
-
# ソースディレクトリ（省略すればカレントディレクトリ）
-
SOURCE=src
-
-
# ドキュメント出力ディレクトリ（省略すればカレントディレクトリに出力）
-
OUTPUT=doc
ドキュメント生成コマンドを実行するとドキュメントが生成されます。
-
$ ./phpxref.pl
[参考サイト]
- PHPXref - The PHP Cross Referencing Documentation Utility[本家]
- Do You PHP? - PHPXref - クロスリファレンスドキュメントの自動生成
出力サンプル
CakePHP1.1.17.5612のソースを各ツールで出力してみました。
クラス構造を確認するならDoxygenが、ファイル構造を確認するならPHPXRefが良さそうです。ただDoxygenにはクセがあるようで、PEARパッケージのようにファイル名とクラス名が異なる場合は上手く生成ができませんでした。（良い方法があればどなたかヘルプを・・・;-)）
- Newer: CakePHPガイドブック登場
- Older: モバイル向けGoogle AdSenseをPHPで使う
コメント (Close):4
- sdozono 07-10-13 (土) 22:44
-
面白いですね。私もPHPXRefで同じことをしていました。cssをなんとか見栄えよくできないか、と思ってます。
- shinbara 07-10-16 (火) 16:33
-
どうもですー。
PHPXRefは良いですね。動作も軽いんでソース見るのに向いてます。 - さとし 07-10-30 (火) 13:40
-
ドキュメント自動生成ツール【A HotDocument】
http://www.hotdocument.net/
を使っています。日本製だから、どのツールより綺麗に出ますね。
VB/C++/C#/Javaを使っています。 - レシ 10-04-19 (月) 1:21
-
残念ながら、生成結果のリンクが切れてました。
トラックバック:0
- このエントリーのトラックバックURL
- http://www.1x1.jp/blog/2007/10/php_source_document.html/trackback
- Listed below are links to weblogs that reference
- PHPソースからドキュメントを生成するツール from Shin x blog
