読者です 読者をやめる 読者になる 読者になる

すたらブログ

文系Webプログラマの備忘録

phpDocumentorを使いはじめました

PHP

XAMPPにはもともとPEARとphpDocumentorが入っているので、それをアップグレードしました。

環境

  • OS: Windows7 64bit
  • XAMPP: 1.8.3
  • phpDocumentor: 2.6.1

アップグレード

下記のページとほとんど同じなので、詳しくはリンク先を御覧ください。

(参照: PleiadesのxamppでphpDocumentor(phpdoc)を使う - モーグルとカバとパウダーの日記)

  1. C:\xampp\phpへのパスを通す。
  2. 管理者権限でコマンドプロンプトを起動し、PEARをアップグレードする。
  3. 古いphpDocumentorをアンインストールし、最新版をインストールする。
  4. phpdoc --versionでバージョンを確認する。

使用上でつまづいたこと

"ファイルの説明がない"と警告される

生成したドキュメントのReports > Errorsで、0行目に以下のエラーがあると警告されます。

No summary was found for this file

解決するには、以下のようにクラスや関数の説明とは別にファイルの説明を用意します。

例1
<?php
/**
 * ファイル全体の説明
 */

/**
 * クラスの説明
 */
class MyClass
{
    ...
?>
例2
<?php
/**
 * ファイル全体の説明
 *
 * 詳細な説明<br>
 * 詳細な説明
 *
 * @author Yuusaku Miyazaki
 */

/**
 * クラスの説明
 */
class MyClass
{
    ...
?>

"プロパティの説明がない"と警告される

先ほどと同じくReports > Errorsで以下のような警告が。

No summary for property $foo
エラーが出る
<?php
/**
 * クラスの説明
 * @property integer $foo とあるプロパティ
 * @var string $bar または、このように
 */
class MyClass
{
    private $foo;
    protected $bar;
?>
合格
<?php
/**
 * クラスの説明
 */
class MyClass
{
    /** @var integer とあるプロパティ */
    private $foo;

    /**
    * または、このように
    * @var string
    */
    protected $bar;
?>

"GraphVizがない"と警告される

コマンドプロンプトでドキュメントを生成しようとすると、下記の警告が表示されます。

Transform analyzed project into artifacts  .. Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?   0.185s

無視してもいいのですが、せっかくですから"GraphViz"を導入してみます。

  1. "GraphViz"をインストールする。
    GraphViz ("Download"からWindows用インストーラを選択する)
  2. "dot.exe"までのパスを通す。
    下記を環境変数Pathに追加する。
    C:\Program Files (x86)\Graphviz2.38\bin
  3. OSを再起動する。

結果、PHPDocの生成時にこのような簡単なクラス図も生成されるようになりました。

が…、いまのところ複雑なクラスを作るつもりはありませんし、ドキュメントの作成に2秒近くかかるようになったので(以前は0.2秒ほど)、アンインストールして環境変数Pathからも削除しました (-_-;)

残る疑問点

私の環境では、コマンドプロンプトで一度pearのコマンドを実行しないとphpdocが実行されません。
下記のようにエラとなります。

Could not open input file: \phpdoc

下記のように、何らかのPEARのコマンドを一度実行しておく必要があります。
コマンドプロンプトを閉じると、またやり直さなければなりません。

pear list
phpdoc -d ./ -t PHPDoc