phpDocumentorを試してみた

GWですね。こんにちは。
妻と3才の息子が妻の姉家族とイチゴ狩りに行っています。GWですね。
※自分は4ヶ月の長女とお留守番

最近、phpDocumentorを触ってみました。
いまさら感がもの凄いのですが、上手く活用したら
めちゃくちゃ便利やろこれって話を書きますです。

インストール

ちなみにCentOSです。
※バージョンは 6.2

$ cat /etc/redhat-release
CentOS release 6.2 (Final)

以下を参考にインストールしました。
madroom project: phpDocumentor 2のインストール手順(Mac/Win/Linux)

※GraphVizをCentOSにインストール

GraphVizを入れると、phpDocumentorでクラスの相関図も
出力されていい感じなので入れます。

$ sudo yum install -y graphviz graphviz-gd

※GraphVizを入れていないと、上のphpDocumentor 2のインストール手順にもありますが、phpdoc実行時にこんなメッセージがでると思います。

Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?

使い方

インストールが終わったら使い方は簡単。

$ phpdoc -d [入力ディレクトリ] -t [出力ディレクトリ]

でOK。

例）
/home/www/configure/〜 を、/home/www/docroot/docsに出力したい場合

$ phpdoc -d /home/www/configure -t /home/www/docroot/docs

※phpdocから省きたいディレクトリがある場合

$ phpdoc -d [入力ディレクトリ] -t [出力ディレクトリ] -i [省くディレクトリ]

例）
/home/www/configure/〜 を、/home/www/docroot/docsに出力したいけど、
/home/www/configure/Hoge/ は省いて出力したい場合

$ phpdoc -d /home/www/configure -t /home/www/docroot/docs -i /home/www/configure/Hoge/

注意点

phpDocumentorを使ってみて、出くわしたメッセージと解決方法を以下に。
※解決方法は以下を参考にさせて頂きました。
<a href="http://www.hazymoon.jp/php/phpDocumentor/" target="_blank">phpDocumentorでドキュメントの自動生成</a>

No page-level DocBlock was found in file XXXX

簡単に言うと、そのファイルの説明が無いおって意味です。
1ファイル1クラスとかそういうルールでやっていると、
ものすごーくめんどくさい。

例）怒られる

<?php

/**
 * Hogeクラスだよん
 */
class Hoge
{
}

例）怒られない

<?php

/**
 * Hogeクラスについて書いています
 */

/**
 * Hogeクラスだよん
 */
class Hoge
{
}

例が大雑把すぎるけど、こういう事。
ものすごくめんどくさいけど。
ファイルの説明もちゃんと書きましょうって事です。
PHPって自由に書けるからね〜。
まぁ、しょうがないっすね〜。
ものすごくめんどくさいけど。

No DocBlock was found for \Hoge

クラスコメント無いお！

No DocBlock was found for method hoge()

メソッドコメント無いお！

No short description for method piyo()

ちゃんとメソッドコメント書けお！

例）怒られる

<?php

/**
 * @test
 */
public function hoge()
{
}

例）怒られない

<?php

/**
 * hogehogeするぞ
 * @test
 */
public function hoge()
{
}

これは自分がUnitTestのコードを出して見た時、出くわしました。

Argument $XXX is missing from the Docblock of hoge()

ちょww引数(@param)書いてないお！

例）怒られる

<?php

/**
 * hogehogeする
 */
public function hoge($in)
{
}

Parameter could not be found in hoge()

ちょww引数無いのに@param書いてるお！

例）怒られる

<?php

/**
 * hogehogeする
 * @param string
 */
public function hoge()
{
}

ん〜、他にも色々あると思うけどこのくらいで。
こちらを見ればバッチリだと思うので参考にしてください。

• phpDocumentorでドキュメントの自動生成
• PhpDocumentor Manual

サンプル

最後に自分で軽く試してみたサンプルを。
色々試しに書き込んでいるので、何か参考にして頂ければと。
※subpackageとかバックスラッシュ()で区切るといい感じみたい。

http://shimabox.net/sample/phpDocumentor/docs/

こちらを見てみると分かる様に、Class inheritance diagram のリンクでクラス相関図が表示されるのでこれは便利かなぁと。
プロジェクトで出すのもいいけど、小さいクラス群とかね。きっと、よかですよね〜。

それと、やっぱりソースをきちんと管理出来たらかっこいいっ！
という事でphpDocumentorオススメです。

あと、一応サンプルのソースを。