phpDocumentorの使い方【コメントからドキュメント作成】

2020.12.05

phpDocumentorを使ってみたので、使い方をまとめています。
phpDocumentorはphpで書かれているソースコードからドキュメントを作成してくれるツールです。

phpのバージョンは7.2.5以降でないと使えません。

公式のサイトはこちら

phpDocumentorのインストール

リリースページからphpDocumentor.pharファイルをインストールしてきます。

このようにリンクをクリックするとダウンロードできます。

phpDocumentorを使う

phpDocumentor.pharをダウンロードしたら使いたいプロジェクトの配下に配置します。

配置したら、ターミナルからコマンドを打つとドキュメントを作成してくれます。

$php phpDocumentor.phar -d . -t ./document/

もしくは、このように実行フォルダ配下に移動させると

$ chmod +x phpDocumentor.phar
$ mv phpDocumentor.phar /usr/local/bin/phpDocumentor

下記のようにグローバルに使うことができます。

$ phpDocumentor -d . -t ./document/

使用する時のオプションは-dがドキュメント化するコードの指定です。

-tが作成されたドキュメントの出力先になります。

例えば、Laravelのcodelike_bbsのドキュメントをプロジェクト配下のdocumentディレクトリに作るには下記のようにします。

codelike_bbsディレクトリ配下にphpDocumentor.pharを移動します。

移動した後にコマンドを実行することで、codelike_bbs/document配下にドキュメントファイルが作成されます。

$php phpDocumentor.phar -d . -t ./document/

実行すると、下記のようにドキュメント作成が進んでいきます。

$ php phpDocumentor.phar -d . -t ./document/
phpDocumentor v3.0.0

Parsing files
 1875/6250 [========>-------------------]  30%02:42:25 ALERT     [app]   Unable to parse file "vendor/mockery/mockery/tests/Mockery/DummyClasses/Namespaced.php", an error was detected: "" is not a valid Fqsen.
 2054/6250 [=========>------------------]  32%02:42:26 ALERT     [app]   Unable to parse file "vendor/monolog/monolog/tests/Monolog/Formatter/FlowdockFormatterTest.php", an error was detected: The tag "@ covers Monolog\Formatter\FlowdockFormatter::for
matBatch" does not seem to be wellformed, please check it for errors

Laravelプロジェクト配下に実行すると、結構時間がかかりました。(15分ほど…)

作成されたドキュメントの確認

指定したディレクトリの配下にhtmlファイル群ができています。

今回の例で言うと、codelike_bbs/document配下にファイルができます。

document/index.htmlを開くと、このような感じになっていて左にNameSpaceでメニューができています。

右上の検索窓ではクラス名やインスタンス名などで、検索ができるようになっています。説明文の日本語でも検索できます！

一覧には緑の丸で表示されていて、Pがプロパティ・Nがネームスペース・Cがクラス・Iがインターフェースです。

リンクを開くと、それぞれのクラスやメソッドに書いたコメントが表示されます。

下記はcodelike_bbsの掲示板を新規作成するメソッドのコメントが表示されています。

引数で渡されているインスタンスのクラスや戻り値のクラスにもリンクが貼られていて、それぞれ確認できるので良い感じです。

phpDocumentorのコメントの書き方

コメントの基本的な書き方を記載しています。

このような感じで、/**から初めて、*/までがドキュメントコメントになります。

/** 1行のdocコメント */

/**
* 複数行のdocコメント
*/

下記では、よく使いそうなタグのみを使用して記述してみました、使えるタグは公式のこちらで確認できます。

クラスコメント

クラスにもコメントしてドキュメント化できます。

@versionがバージョンで、@authorが作成者、@linkは書いておくとドキュメントにリンクをつけることができます

/**
* Foodクラス
* @version 1.0.0
* @author y.hirano
* @link https://codelikes.com/phpDocumentor
*/
class Food {
    // .....
}

上記のようにコメントを記載すると、このようになります。

メソッドコメント

メソッドコメントには1行目に説明を書きます。

2行目から@paramで渡すパラメータを指定します。@param [パラメータの型] [パラメータ名] のような形で記述します。

パラメータを書いたら、最後に@returnで返す値を記載します。

/**
 * 新規掲示板保存
 * @param BoardCreateRequest $request
 * @param CreateMakeBoardCase $case
 * @return RedirectResponse
 */
public function save(BoardCreateRequest $request, CreateMakeBoardCase $case)
{
    // .... 省略 ......
}

このように書いておくと、phpDocumentorを実行したときに、HTMLドキュメントが作成されて、このように表示してくれます。

phpDocumentorでの出力サンプル

クラスをふたつ用意して、出力したときのサンプルをこちらから確認できます。

作成してみたクラスは下記になります。

Foodクラス

<?php
/**
 * Foodクラスファイル
 * @license MIT
 * @link https://codelikes.com
 */

 namespace BlogDemo;

/**
* Foodクラス
* @version 1.0.0
* @author y.hirano
* @link https://codelikes.com/phpDocumentor
*/
class Food {
    /** @var string $name */
    private $name;

    /** @var string $color */
    private $color;

    /** @var string $taste */
    private $taste;

    /**
     * 名前の値を取得
     * @return string
     */
    public function getName() {
        return $this->name;
    }

    /**
     * 名前の値を設定
     * @param string $name
     * @return void
     */
    public function setName($name) {
        $this->name = $name;
    }

    /**
     * 色の値を取得
     * @return string
     */
    public function getColor() {
        return $this->color;
    }

    /**
     * 色の値を設定
     * @param string $color
     * @example #ffffff カラーコードで設定
     * @return void
     */
    public function setColor($color) {
        $this->color = $color;
    }

    /**
     * 味の値を取得
     * @return string 
     */
    public function getTaste() {
        return $this->taste;
    }

    /**
     * 味の値を設定
     * @param string $taste
     * @example 甘い|辛い|苦い|酸っぱい 文字列で指定する
     * @return void
     */
    public function setTaste($taste) {
        $this->taste = $taste;
    }

    /**
     * foodの情報出力
     * @return void
     */
    public function output() {
        echo "名前 :{$this->name} 色:{$this->color} 味:{$this->taste}";
    }
}

Fruitクラス

<?php
/**
 * Fruitクラスファイル
 * @license MIT
 * @link https://codelikes.com
 */

 namespace BlogDemo;

/**
* Fruitクラス
* @version 1.0.0
* @author y.hirano
* @link https://codelikes.com/phpDocumentor
*/
class Fruit extends Food {
    /** @var int $size */
    private $size;

    /** @var int $shape */
    private $shape;

    /** $var array $shapeText */
    private $shapeText = [1 => '丸', 2 => '平たい', 3 => '三角', 4 => '四角'];

    /**
     * サイズの値を取得
     * @return int
     */
    public function getSize() {
        return $this->size;
    }

    /**
     * サイズの値を設定
     * @param int $size
     * @return void
     */
    public function setSize($size) {
        $this->size = $size;
    }

    /**
     * 形状の値を取得
     * @return string 
     */
    public function getShape() {
        return $this->shapeText[$this->shape];
    }

    /**
     * 形状の値を設定
     * @param int $shape
     * @return void
     */
    public function setShape($shape) {
        $this->shape = $shape;
    }

    /**
     * fruitの情報出力
     * @return void
     */
    public function output() {
        echo "名前:{$this->getName()} 色:{$this->getColor()} 味:{$this->getTaste()} サイズ:{$this->size} 形状:{$this->shapeText[$this->shape]}\n";
    }
}

リンクからドキュメントを確認してもらうと、上記のクラスとメソッドがドキュメント化されていることが確認できます。

PHP
yasuaki

コメント