最近いろいろ便利なクラスなどと出会い、ソースを覗いてみたりするとコメントアウトの書き方に違和感を覚えた。
というのもコメントアウトが汚いのです。

/**
 * Comment
 * @param someParamators
 */
function function_name (argument) {
    // body...
}

こんな感じ。
しかしこの手のコメントアウトが流行ってるのは確かでこれは何かあるのかもしれないと色々調べていたら○○Docという書式があるらしい。すばらしい！汚いなんていってごめんなさい。

ActionScriptや、JavaScriptによってASDocとかJSDocとか言語ごとにルールがあるのだけど要するにコメントアウトの書式をこれらに準拠して作成すると、コンパイルしてHTMLドキュメントにしてくれるらしい。

伝えづらいのでとりあえずサンプル。
ActionScriptからはTweenerクラス、JavaScriptではShadowBox2.0クラスをそれぞれ文書化してみました。

とくにASDocなんてAdobeのhelpみたいですね。
それもそのはず、ASDocはFlexSDKにふくまれるAdobe謹製。
javascriptはJSDoc Toolkitを使いました。

使い方はそれぞれ以下より。

ASDocはFlexSDKについていて、JSDocはGoogleCodeよりDLしました。

他にもjava, PHP, Rubyなどなど様々な○○Docが作成される模様。
CSSDocなんてものもあるみたい。

最終的に統合された一つの書き方になるといいなと願いつつもやっぱ言語ごとに仕様が違うから難しいのかな。
とりあえずこれらの書式を覚えていきたいと思います。