phpDocumentor でドキュメント自動生成してみた

  • このエントリーをはてなブックマークに追加
  • Pocket

こんにちは、エンジニアの榎本です。

チーム開発において、ファイル数やクラスが増えてくると、新しいメンバーに説明をする際など、ドキュメントがないと説明が難しくなってくることがあります

しかし実際のところ、ドキュメントを作成する工数を確保できず、せっかく作ったドキュメントがあってもどんどん陳腐化している現場も多いのではないでしょうか

そのため、今回は phpDocumentor を用いて PHP のコードから自動でドキュメントを生成する方法を紹介したいと思います

作業環境

  • CentOS 7.2
  • PHP 7.0.12
  • Composer 1.2.2

phpDocumentor のインストール

まずは新規にディレクトリを作成し、Composer で phpDocumentor をインストールします

これでインストールが完了です

Composer でインストールすることができるのでとても簡単ですね(開発環境でのみ使用すると思いますので --dev オプションを忘れないように気をつけてください)

それでは、インストールが完了したのでバージョンを確認してみます

Composer で phpDocumentor が問題なくインストールされたことが確認できたので、ドキュメントの生成元のコードを簡単に書いてみたいと思います

  • app/util/tax.php

  • app/controllers/product.php

たった2ファイルの簡単な PHP のコードですが、上記のコードから早速ドキュメントを自動生成してみたいと思います

ドキュメントの自動生成

ドキュメントの生成には phpdoc run コマンドを使用します(今回は phpdoc コマンドは Composer でインストールしたものを使用しているので注意してください)

phpdoc run コマンドのオプションですが、d オプションでコードが置かれているディレクトリを指定し、t オプションでドキュメントの生成先ディレクトリを指定します。

今回は public/doc に自動生成されたドキュメントを配置するように指定しました。

それではドキュメントが生成されたのでブラウザで確認してみます。

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-0028-11-04-21-34-58-1

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-0028-11-04-21-35-07-1

たった2ファイルしかなかったので、中身が少ないですが、このようにクラスのメソッドの一覧や、メソッドの引数の一覧などがブラウザ上から確認できるようになりました

クラスの階層構造を可視化する

phpDocumentor はドキュメントの自動生成時にクラスの階層構造を図式で可視化することもできるので、どのような図式ができるのか試してみます

まずは、必要なライブラリを yum でインストールします。

インストールが完了したら、もう一度 phpdoc run コマンドでドキュメントを作成してみます。

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-0028-11-04-21-35-17-1

このような図が表示されたら OK です!

まとめ

phpDocumentor を使用して、PHP のコードから自動でドキュメントを生成してみました

クラスの階層構造を可視化することもできるので、新しいメンバーがプロジェクトの全体像を把握することもブラウザ上で簡単に行うことができ、プロジェクトの説明を行う際などにも役立つと思います

Composer でとても簡単にインストールすることができ、導入への障壁がかなり低いので、ぜひ皆さんのプロジェクトにも導入してみてはいかがでしょうか

  • このエントリーをはてなブックマークに追加
  • Pocket

SNSでもご購読できます。

コメントを残す

*