引数の指示などは nakodoc のようなものを実装すべきだと思います。
javadoc のような感じで（というかほぼまんま）書いたみたもの：
/**
* ほがほがの処理を行うグループ。
* @公開
* @継承 ミックス
*/
■グループ名 +ミックス
/**
* Aでふがふがの処理をする。
* @引数 A ほげほげの値
* @例 グループ名で「A」をメソッドする。
*/
・メソッド(Aを)～
/**
* ふげふげの値を保持する
* @非公開
*/
・プロパティ
マウスカーソルを合わせた時にその(nakodocの)情報が出る、というのがあると
開発環境として便利だと思います。