PHP で JavaDoc 風 (phpDocumentor) コメントを書くとき...

メソッドが期待する GET パラメータとか POST パラメータって
みんなどうやって記述してるんだろう...。

これはソシャゲーのコードを書き始めてからずっと気になってる事。

そもそもソースコード内にはスーパーグローバルは記述しないようにシステムのユーティリティに任せるよね?
$_GET をそのまま書いてもいいけど、その度に htmlspecialchars() したりするの嫌じゃない...?

本題に戻ると、「その時点」で GET の (または POST の) hoge とか moge っていうパラメータが必要な場合がある。
そうすると、そのメソッドが期待通りの動作するためには
GET の hoge ってパラメータが必要ですよ、とコメントにしろドキュメントにしろ、明示する必要があると思うんだ。

そしてそれが phpDocumentor で生成されたドキュメント上から閲覧できたらすんばらしい!
と思った。思いつき。思いつきすんばらしい!

でも、そもそも Doc 系は REST の API を記述する構文がない。
だからコメントの中で
「$_GET['hoge'] ... HogeController::moge() アクションから要求されたパラメータです.」
「$_POST['fuga'] ... HogeController::posted() アクションから送信されたパラメータです.」
のような書き方をしなければいけない.

面倒臭い!

「$_GET['hoge'] って書かれてりゃ、コメントなくてもソース読めば分かんだろボケ」

とか言われるかもしれないけど、ソース読めって暗号は開発者にしか伝わらないわけで。
じゃあ開発者以外が GET POST を理解してドキュメントを読めるのかって話もあるよね...ぁー面倒。


しかし、やりたいことはただ一つ。
phpDocumentor で出力されるドキュメントに、REST パラメータもある書式に乗っ取って出力したい!
ということ。

なんとかできないかなぁ...