|
 現在では、PEARのAPIドキュメントなどはphpDocumentorが使われるようになっています。
仮に、あるプロジェクトで作成したクラスを他のプロジェクトでの使いたい場合、「ソースを追ってAPIを調べてね」なんてやってると余計な工数がかかってしまいますし、いつの間にか自分自身も忘れてるってことあります。そこで、何らかのAPIドキュメントがあると非常に楽ですよね。
Javaにはjavadocという強力なツールが用意されていますが、PHPでそれに相当するのが、PHPDocです。
PHPDocは、PHPDoc本家、あるいは、PHP本家のcvsリポジトリから入手することができます。
PHPDoc本家から入手したzipは、ブラウザからアクセス可能な適当なディレクトリに展開します。CVSの場合も、ブラウザからアクセス可能な適当なディレクトリにcheckoutしておきます。
まずは、PHPソースにコメントを入れます。基本的には、作成されるドキュメントにそのまま表示されます。また、javadocのドキュメントコメントがほとんどそのまま使えます。以下がサンプルで、こちらからもダウンロードできます。
●コメントの例（クラスの説明）
<?php
●コメントの例（メソッドの説明）
<?php
?>
次に、PHPDoc/index.htmlの以下の項目をあなたの環境に合わせて修正します。
-
PHPDOC_INCLUDE_DIR：PHPDocのincludeパス
-
PHPDOC_LINEBREAK：PHPソースの改行コード（CVS版だと、php_uname()の値が「Windows」かどうかで自動的に設定するようになっています）
-
$doc->setApplication()の引数：ドキュメントのタイトル
-
$doc->setTarget()の引数：ドキュメント化するPHPソースへの絶対 or 相対パス
-
$doc->setTemplateDirectory()の引数：ドキュメントテンプレートへの絶対 or 相対パス
-
$doc->setSourceFileSuffix()の引数：ドキュメント化するPHPファイルの拡張子
そして、ブラウザからアクセスするとドキュメントが作成されます。なお、PHPDoc/apidoc/keepに以下の4ファイルがあるので、それらをドキュメントが作成されたディレクトリにコピーして完成です。
- empty.html
- index2.html（コピーする際にindex.htmlにすると便利かも）
- phpdoc.css
- phpdoc.dtd
こうして作成したサンプルはこちらです。
 [2002/02/19] クラスの説明（description）にコードを記載したい場合とかありますが、PHPDocでは改行が全て削除されてしまいます。改行をそのままドキュメントに反映させたい場合、parser/PhpdocParserCore.php内のgetDescriptionメソッドの最後にあるimplode関数（477行目あたり）の第1引数を「""」から「"\n"」に変更します。そうすると、こちらのようになります。
[以下、2002/11/09追記] 遅ればせながら、PEARパッケージのPHPDocも試してみました。今回はPHP4.3.0pre2（CLI版）を使って確認をしました。Web版との大きな違いはコマンドラインで利用できるようにPEARコアコンポーネントのSystemやConsoleが組み込まれていることですが、基本的にはPHPスクリプトです（ある意味当然。。。）。
インストール方法やdocコメントなどの情報も、PEARマニュアルにまとめられていていますので、是非参照してみてください（訳者の方に感謝です）。ここでは、簡単なインストール方法を示しておきます。
# pear install PHPDoc
downloading PHPDoc-0.1.0.tar ...
...done: 598,528 bytes
install ok: PHPDoc 0.1.0
# which phpdoc
/usr/local/bin/phpdoc
#
PEARマニュアルにもありますが、引数に何も指定しないで実行するとヘルプが表示されますので、一通り見ておきましょう。
$ phpdoc
Usage: phpdoc [-h] [-f] [-i <dir>] [-s <dir>] [-d <dir>]
Options:
-s <dir> directory where your source files reside
-d <dir> destination dir (save the generated docs here)
-t <dir> template dir (path to the templates)
-e <name> template name (default='default')
-f force the deletion of the destination directory
-h, -? display help/usage (this message)
You could also set defaults values editing the header of this script
$
実際に実行する場合は、こんな感じになります。
$ phpdoc -s src/ -d doc/
Parser starts...
... preparse to find modulegroups and classtrees.
... parsing classes.
... parsing modules.
... writing packagelist.
Parser finished.
Starting to render...
API Docs for src/ done in doc/
6 seconds needed
$
で、ざっと使ってみる（あるいは、PHPDoc以下のスクリプトを見る）と、従来のWeb版と（ほとんど）変わりないことが分かります。つまり。。。
- ドキュメントのタイトル（「PEAR Repository」で固定）
- ドキュメント化するPHPファイルの拡張子（phpとincで固定）
これらを変更するにはphpdocそのものを修正すれば良いわけですが、コマンドラインでいちいち修正するのも面倒です。ということで、これらをオプションで指定できる簡単なパッチを作ってみました。パッチの適用方法と適用後のヘルプは、以下のような感じになります。
# patch /usr/local/bin/phpdoc < phpdocex.patch
patching file /usr/local/bin/phpdoc
# phpdoc
Usage: phpdoc [-h] [-f] [-i <dir>] [-s <dir>] [-d <dir>] [-c <name>] [-x <ext>] [-X <ext>]
Options:
-s <dir> directory where your source files reside
-d <dir> destination dir (save the generated docs here)
-t <dir> template dir (path to the templates)
-e <name> template name (default='default')
-f force the deletion of the destination directory
-c <name> documentation title
-x <ext> add target file extension (ex. phtml,phl...)
-X <ext> replace target file extension (ex. phtml,phl...)
-h, -? display help/usage (this message)
You could also set defaults values editing the header of this script
#
「-x」「-X」の違いですが、標準ではphpとincが拡張子として指定されますが、
- 「-x」は指定した拡張子を対象として追加
- 「-X」は指定した拡張子のみを対象とする
な具合になります。パッチを見れば何をやっているかは、すぐに分かると思います。実際の使い方はこんな感じになります。
$ phpdoc -s src/ -d doc/ -c "sample classes" -x phl
：
なお、Web版のメモにある「クラスの説明（description）にコードを記載したい場合」については、（まだ）対応してません。。。(^-^;
|