phpDocumentor

目次
1 phpDocumentorのインストール
 1-1 パッケージの入手
 1-2 インストール (Unix/Linux)
 1-3 実行
 1-4 その他補足
2 使い方
 2-1 phpdocコマンドの実行
 2-2 コメントの記入について
  ・ 基本
  ・ 定数のコメント
  ・ @author
  ・ @global
 2-3 タグについて
  ・ @link
  ・ @package
  ・ @param
  ・ @return
  ・ @see
  ・ @subpackage
  ・ @var
 2-4 インラインのタグについて
  ・ @link
 2-5 ちょっとしたメモ
  ・ 対象ファイル拡張子の設定

PHPスクリプトに埋め込んだコメントから、ドキュメントページ（HTML)を生成してくれるツールです。
自分でせこせことWordとかにまとめるよりもラクですし、何よりコメントとして記述もされるわけですから
見直すときも参照しなくてもよいからラク。
コメント更新してもコマンド一発でドキュメント更新も出来るから手間も省けると。

ただ一寸導入に手間取ったので、簡単にメモを書いておこうと思う次第です。

1 phpDocumentorのインストール
1-1 パッケージの入手
 phpDocumentorの公式サイトよりアーカイブをダウンロードしてきます。
1-2 インストール (Unix/Linux)
 パッケージはtar.gz形式で圧縮されていますので、tar -zxfで解凍してください。
解凍後、phpDocumentor-<バージョン>というディレクトリが出来ると思います。
そのディレクトリを任意の場所に移動すればOKです。
また、phpDocumentor-xxx/phpdocというシェルスクリプトの中にある、PHP="/usr/bin/php"にphpコマンドへのパスを、各自の環境に合わせて設定してください。
1-3 実行
 phpDocumentorインストールディレクトリ以下にある、phpdocファイルが本実行ファイルとなります。
phpDocumentorインストールディレクトリ以下に移動し、./phpdocで実行します。
1-4 その他補足
 扱いはシェルスクリプト/PHPスクリプトと変わりませんので、phpDocumentorインストールディレクトリをinclude_pathに含め、phpdocへのシンボリックリンクを/usr/binあたりに設定する、などのほうがラクかもしれません。

phpDocumentorはpearのほうからもインストールが可能でしたが、pearのほうはウチの環境では動作が怪しかったです。
またpearのphpDocumentorをインストールしているとそちらが優先されるため、手動で設定した内容が反映されなかったり、バージョン互換の問題が発生したりする可能性があります。

ページのINDEXへ

2 使い方
 至極単純な話、phpスクリプトに一定の形式でコメント行を記入し、それを読み込ませます。
すると指定したディレクトリにドキュメントHTMLファイルが生成されます。

2-1 phpdocコマンドの実行
 > phpdoc -d <PHPソースファイルのディレクトリ> -t <ドキュメントを生成するディレクトリ>
<ドキュメントを生成するディレクトリ>内に、ソースファイルを元としたドキュメント一式が生成されています。

2-2 コメントの記入について
 詳しくは本家ユーザーズマニュアルを参照ください。
よく遣いそうなものをメモしておきます。
・ 基本
 /** ... */で囲んだコメントが、処理の対象となります。
例えば最初のファイル説明では、
/**
* ファイルの説明 (一行)
*
* ファイルの説明 (複数行)
* HTMLに反映されたとき改行はされない
* @package パッケージ
* @author 著作者
* @version 1.00
*/
などと書きます。

/** コメントとか */
のように一行にまとめることも可能です。

また、以下のHTMLタグが使用可能で、HTMLドキュメント出力時に反映されます。
(phpDocumentor Tutorialより引用)
  • <b> -- emphasize/bold text
  • <code> -- Use this to surround php code, some converters will highlight it
  • <br> -- hard line break, may be ignored by some converters
  • <i> -- italicize/mark as important
  • <kbd> -- denote keyboard input/screen display
  • <li> -- list item
  • <ol> -- ordered list
  • <p> -- If used to enclose all paragraphs, otherwise it will be considered text
  • <pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
  • <samp> -- denote sample or examples (non-php)
  • <ul> -- unordered list
  • <var> -- denote a variable name
    •
    ・ 定数のコメント
     定数定義の前にコメントしたものが使われる。
    /**
    * 定数のコメントです
    */
    define ("DEF_VALUE", 1);

    ・ @author
     @author 著作者
    著作者を記載します。

    ・ @global
     @global 型 $グローバル変数名
    @global 型 コメント
    グローバル変数としてのコメントを記入します。
    /**
    * グローバル変数の説明
    * @global boolean $global_flg
    */
    $global_flg=true;
    のように、ひとつづつ記入します。

    2-3 タグについて
    ・ @link
     @link リンク先URL 表示用文字
    URLはhttp://から記入します。

    ・ @package
     @package パッケージ名
    当該ファイル(と当該ファイルに含まれているクラス)のパッケージを指定します。
    指定がない場合はdefauitにカテゴライズされます。

    ・ @param
     @param 型 $パラメータ変数名 コメント
    関数の引数となるパラメータを記載します。

    ・ @return
     @return 型 コメント
    関数の戻り値を記入します。

    ・ @see
     @see 参照先関数、ファイル名またはクラス名
    参照する先の関数またはクラス名を指定すると、その場所へのリンクが作成されます。
    ファイル名の場合は＜ファイル名＞、
    関数の場合は＜関数名＞()、
    クラスの場合は＜クラス名＞、
    クラス内の関数の場合は＜クラス名＞::＜関数名＞()
    とします。

    ・ @subpackage
     @subpackage サブパッケージ名
    パッケージわけを行った下に、さらにもう一段パッケージ分けを指定します。

    ・ @var
     @var 型 説明
    クラス内で定義されたvar変数の説明です。

    2-4 インラインのタグについて
     コメント中に記入するタイプのタグです。{@link <URLまたは関数名>}などとします。
    ・ @link
     タグの@link または @seeを参照

    2-5 ちょっとしたメモ
    ・ 対象ファイル拡張子の設定
     phpDocumentorでは、処理対象のファイルかを判断する際に、まず拡張子で判断しようとします。
    対応する拡張子を増やしたい/減らしたい場合は、phpDocumentor.iniファイル内の
    [_phpDocumentor_phpfile_exts]
    以下に列挙されている拡張子を調整してください。

    デフォルトではphp, php3, php4, phtml, incが処理対象として設定されてますが、
    例えば、*.phlファイルも追加したいと思ったときは、一行追加してphlと記入します。

    ページのINDEXへ
    TIPS INDEXへ
    Last modified: Sun Jun 23 19:26:31 2004