Laravel
PHPのシステムドキュメントを楽して作りたい
ヤス
更新日:2021/10/27
目次
はじめに
複数人で保守が必要な大～中規模なシステムの場合、システムのドキュメントが欲しいのですが、
1から手作業で作るのは手間がかかるので、自動でドキュメントを作成する方法調べました。
phpDocumentorが良さそう
PHPで手軽に導入できるツールが欲しかったので色々調べた結果、phpDocumentor が良さそうなので試してみました。
その他の候補
- Doxygen → 初期状態だとPHPはうまくドキュメント化できなかった。設定の調整が大変そう ＋ 出力結果のUIが個人的にいまいちだったので断念。
- Laravel+Scribe → APIのドキュメント化に特化している。公式HPの設定通りにインストールしたがうまく動作しなかったので一旦断念。
phpDocumentorの導入
HP にある、PHARを使った方法を使いました。
PHARファイルをダウンロードするだけなので、環境設定を変える必要がないので便利でした。
|
1 |
wget https://phpdoc.org/phpDocumentor.phar |
|
1 |
chmod +x phpDocumentor.phar |
実際に使ってみた
最新作成した Laravel のシステムを使ってドキュメントを作成してみました。
-dが作業ディレクトリ、-tが出力先ディレクトリ、–ignoreが除外したいディレクトリになっています。
（Laravelはデフォルトで作成されているフォルダは除外して作成するようにしました）
|
1 |
php ./phpDocumentor.phar --ignore ./app/Console --ignore ./app/Providers --ignore ./app/Exceptions -d ./ -t docs |
出力結果
簡単にドキュメントの作成ができました。
出力内容を見た限りは、最低限のドキュメントが生成できている印象です。
ファイルで参照している関数等の関連性までは表示されていないので、このドキュメントだけで全てを把握することは難しいです。
最低限でもドキュメントが自動で生成できるのは便利なのでしばらく使ってみようと思います。
コメントの記入例
ドキュメントにコメントを記載するにはphpDocumentor用のコメントを書かないといけません。
使えるタグは公式HP に記載されています。
今回利用したタグをいくつか載せておきます。
|
1 2 3 4 5 6 7 8 |
/** * テストコントローラー * @version 1.0.0 * @author ヤス * @link https://～ ※ドキュメントにシステムURLを記載できて便利 */ class TestController extends Controller { |
|
1 2 3 4 5 6 |
/** * 来年を取得 * @param int $year * @return int */ private function getNextYear($year) { |
