PHP Documentorを使う

phpdocumentorをいまさらながら使うので、メモ。
環境はMac(yosemite)です。

インストール

インストールは、pearかcomposer。基本はcomposerかな？と思うも、pearがrecommendedとなっている。

pear

pearは基本sudoが必要。インストールできたかは、phpdoc -Vで確認。

sudo pear channel-discover pear.phpdoc.org
sudo pear install phpdoc/phpDocumentor
phpdoc -V

執筆時点では2.8.5のようです。

pear upgradeの確認

忘れるのでもメモ。

sudo pear list-upgrades

で確認。
実際のUpgradeは、

sudo pear upgrade <package>

とする。

Composer

今どきはComposer。

composer require --dev phpdocumentor/phpdocumentor

でよいみたい。
利用の際は、

php vendor/bin/phpdoc

で動く。

利用（コマンド）

基本は

phpdoc run -d /コード -t /出力先

テンプレートも指定できる。

phpdoc run -d /コード -t /出力先 --template=clean

テンプレートの種類は、

phpdoc template:list

で確認できる。気分転換が必要なときはいいだろう。もちろん、オリジナルのテンプレートを作ることもできる。

利用（コード）

出力用の最低限度のサンプル。

例えば、テストフォルダに下記のようなtest.phpを作る。

<?php

/**
 * ファイル自体のサマリを書く。書かないと怒られる。
 */


/**
 * 加算機能（概要を書く）。
 *
 * 2つのパラーメータを受け取り加算して返す（詳細を書く）。
 *
 * @param int $x 足し算用パラメータ。
 * @param int $y 足し算用パラメータ。
 *
 * @return int $ans 返り値。
 *
 */
function add($x,$y)
{
    $ans = $x + $y;
    return $ans;
}

/**
 * 減算機能（概要を書く）
 *
 * 2つのパラーメータを受け取り減算して返す（詳細を書く）。
 *
 * @param int $x 引き算用パラメータ。
 * @param int $y 引き算用パラメータ。
 *
 * @return int $ans 返り値。
 *
 */
function sub($x,$y)
{
    $ans = $x + $y;
    return $ans;
}

それで、

phpdoc -d test -t out

とすると、outにドキュメントが出力される。out/index.htmlを開くと、

となる。

基本は、機能概要と引数、返り値くらいを書けばいいだろう。
詳しい情報は、本家サイトのDocumentを必要に応じて見る。