PHPDoc コメントに, 各ページの仕様を記述する

[nanasess]

各ページの process() 関数に, ページの詳細な仕様を記述する. 理想は, ソースコードを追わなくても, ページがどんな振舞いをするか理解できること.

フォーマット案(募集中)

基本的に, RUP 形式のユースケース記述を使用する

• 概要
• アクター
• 基本フロー
• 代替フロー
• 特別な要件事項
• 事前条件
• 事後条件
• サブユースケース

また, 入出力内容を明確にするため, 引数(@param コメント)以外に, 使用するスーパーグローバル変数一覧を記述する.

出力方法

phpDocumentor を使用する.

デフォルトのエンコーディングは, ISO-8859-1 なので, UTF-8 に置換しておく

$ find /opt/local/lib/php -name 'header.tpl' -print | sudo xargs sed -i'.bak' -e 's/iso-8859-1/utf-8/g'

phpdoc コマンドで出力. フォーマット形式は HTML:frames:phpedit がイチオシ.

$ phpdoc -t 出力ディレクトリ -o HTML:frames:phpedit -d data/class

課題など

• PDF 出力は日本語が通らない
• コミットしたら自動的に Web に反映するようにしたい

注意事項

• php.ini で memory_limit = 512M くらいにしないと足りない
• PHP 5.3.x 以降では, php.ini で date.timezone = Asia/Tokyo? などにしないとタイムゾーンの警告が出る

[nanasess]

記述のサンプル

source:/branches/comu-ver2/data/class/pages/entry/LC_Page_Entry.php