ASDocコメントを埋め込もう

コメントをドキュメント向けに

　さて、前回「ASDocを使ってみよう」で、asdocによるドキュメントの生成のしかたを学習したわけだけど、それだけだとオブジェクトやメソッド・プロパティがずらっとならんだだけで、説明がほとんどない。
　これでは、ドキュメントとしては失格だ。結局ソースのコメントを参照しなきゃいけない。

　Adobeのサイトの AppleScript3 のクラスのヘルプには、当然だけどしっかり説明がある。
　ASDocに抜かりはない、ちゃんとソースコードの中に書いた説明コメントもドキュメントの中に反映してくれる。

　でも、コメントを全部書き出されても意味わかんなくね??

基本を見てみよう

　とにもかくにも、Adobeさんの資料を見る。原典に当たるのが基本だしね。
　Flex4.6でのASDoc用タグのリストを見る。
　結構見つけんの苦労しちゃいましたが。日本語の説明はなくなってるのか、もともとないのか、見つけきれなかった。

/**
 * 説明.
 * <p>HTMLで記述する</p>
 */

　基本は、上記のような/**で始まるコメントを、クラス、プロパティ、メソッド、変数の定義の「直前」に書いておく。
　Javadocと一緒だね!

　最初の行の最後が「.」なのは、そこで一覧で表示される簡単な説明を区切るから。
「。」でも区切ってくれよ…格好わるい、とか思うが、そもそも説明自体が短い場合は、別に気にしなくていいし、あんまり長々書く気もないけどね!

　あと、行の先頭にある「*」と空白は、ドキュメントを作る際に無視される。
　じゃあ、書かなくていいんじゃね? とも思ったりするが、ここのところがドキュメントに出力されますよー、という印として、入れておいた方が良いだろう。

　てなわけで、コメントを書く時に「/**」でマーキングするってことさえ分かってれば、ドキュメント向けのコメントは書ける、ということだ。

タグを見てみよう

　で、全部説明の部分に書いちゃえばいいっちゃ良いんだけど、よく書く説明はフォーマットが統一されている方が読みやすいので、「@タグ名」という形のタグを書いておけば、専用のHTMLにレンダリングしてくれる。
　そもそもフォーマットを統一して読みやすく、書くのも楽にしようという目的でASDocを導入するわけなので、極力タグを使って楽していきたい。
　ただ、asdocはバージョンによって結構タグの種類が変わっているようで、初期のころにはasdocが自分でコードに書かれている定義を判別できなくて、わざわざ@kindとか書いてたみたい。
　流石に今はコードに書いてあることを二度書きするみたいな、省力化のつもりが余計手間が増えた的なことは減ってるようで、善きかな善きかな。

　では、主なところを並べてみよう。正確なところは、やはりAdobeさんの資料を見て貰うとして。
　自分が使いそうな感じのやつを主に。

　まずはコード例(@example)、コードは<listing version=”3.0″></listing>タグで囲む(このバージョンはActionScriptのバージョンなのかな?)

/**
 * @example 簡単な説明
 * <listing version="3.0">
 * サンプルコード
 * </listing>
 */

　次は、メソッドの引数(@param)。
　コードに書いた仮引数名がそのままドキュメントに書かれるので、あまり迂闊な変数名を付けると分かりにくいのもそうだけど、格好わるい。
　ドキュメントを自動出力するというのは、コードを読みやすく書くクセがつく効果もありそう。

/**
 * @param 仮引数名 説明
 */

　引数があるなら、当然メソッドの返り値(@return)も。

/**
 * @return 説明
 */

　後は、年月日(@since)。
　開発開始の2014-10-17みたいなテキストを書いておくことにする。

/**
 * @since 年月日
 */

　他にも、継承元のコメントをひっぱってくるヤツとか、色々あるんだけど、ひとまずメソッドの引数と返り値の説明さえしっかりしてれば大丈夫でしょ。
　あと、バージョン(@version)とか、Adobeの解説ページには書いてないけど、試して見ると動く。
　ちなみに、ライブラリのパッケージのソースコード見てみると作者(@auter)が書いてあることが多いんだけど、これはJavadocにはあるし、特に大人数で作業したり、色んなライブラリを使ったりすると、誰が作ったんだか分からないと大混乱するからかと思う。
　なんでASDocでは廃止されたんだ?(前はあったようなのに)
　あと、@seeで他のクラスや関数に付いて言及できるけど、ここに作者サイトURLを書いておく、ってパターンも多い感じ。

まとめ

　とにかくこれで、いちいちソースコードと別にドキュメントを管理する必要がなくなった。
　わーい。