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を必要に応じて見る。