phpDocumentorを使いはじめました

最終更新: 2017-05-05

環境
インストール
書き方
使用上でつまづいたこと

環境

Windows 10
XAMPP 7.1.1
phpDocumentor 2.8.5
Composer 1.4.1

インストール

PEAR経由は失敗する

以前の環境(XAMPP 1.8.3, phpDocumentor 2.6.1)では問題ありませんでした。
しかし、現在の環境(XAMPP 7.1.1, phpDocumentor 2.8.5)では失敗してしまうのでComposerを使ってインストールしました。
一応、以前の方法を紹介します。

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

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

エラーの内容

下記のように、Windowsでは.tgz, .tarを解答できずにエラーになってしまいます。

> pear install phpdoc/phpDocumentor
downloading phpDocumentor-2.8.5.tgz ...
Starting to download phpDocumentor-2.8.5.tgz (8,184,822 bytes)
.........done: 8,184,822 bytes
ERROR: unable to unpack C:\Users\Yuusaku\AppData\Local\Temp\pear\download\phpDocumentor-2.8.5.tgz

(下記でも同じ)
> pear install --nocompress phpdoc/phpDocumentor

参考: php - Windows - PHPDocs unable to install through Pear - Stack Overflow

Composerでインストールする

グローバルで使えるようにインストールします。

> composer global require phpdocumentor/phpdocumentor

ファイルはC:\Users\%USERNAME%\AppData\Roaming\Composerに存在します。

動作確認

# バージョン確認
> phpdoc -V (大文字)

# ドキュメント生成
## ファイルを指定
> phpdoc -f <対象のファイル名> -t <生成するフォルダ名>
> phpdoc -f MyClass.php -t phpdoc

## フォルダを指定
> phpdoc -d <対象のフォルダ名(再帰的)> -t <生成するフォルダ名>
> phpdoc -d MyProject -t phpdoc

書き方

下記をご覧ください。

使用上でつまづいたこと

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

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

No summary was found for this file

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

<?php
/**
 * ファイル全体の説明
 * @author Yuuaku Miyazaki <toumin.m7@gmail.com>
 * @license MIT
 */

/**
 * クラスの説明
 */
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"を導入してみます。