コメントを記述するなら

2010 年 1月 5 日
kosuke

Flashで開発する際、コメントってどうしてます？
僕の場合、自分しかさわらない一度っきりのプロジェクトにいちいち緻密にコメントつける必要性は微妙と思いつつも、見直してみると大抵コメントをつけているようです。
最近はどうせコメントをつけるならとASDocに対応した形式で記述するようにしました。
このASDocの書式には結構多様な指定が出来るようになっています。
刺身のつまみたいなもんなんで、全部覚えようなんて気にはまったくならないのだけども、いざ書き出そうって時にエラーってことが頻繁なんで、自分的な要点を記録しておきます。

先にヘルプのインデックスへリンク。
参考:ASDoc の使用

コメントの記述は以下の書式。/** と */ の間にコメントを書く。
コメント行頭の * は無くても問題なく書き出されるような気がしますが、ASDocで解析するのに使うと参考にあるので記述する。この書式をクラスやメソッド、プロパティなどを記述している直前に書く。この位置にコメントを書くことは多いと思うので、どうせならこれにしておくって感じ。

/** 
* Main comment text.
* 
* @tag Tag text.
*/

参考:ASDoc コメントの作成

@の部分がASDocのタグになっていて、ASDocを書き出す時に整形されます。
参考:ASDoc タグ

いろいろありますが、メソッドやコンストラクタの引数用に@param。戻り値用に@return。くらいしか使っていない。自分用にはこの位でいんじゃないかと思います。僕的にコケたところで、getter/setterの場合、ASDocのコメントは1カ所に書きます。

/**
 * 直線を定義します。
 */	
public class Line{
 
	/**
	 * 直線を定義します。
	 * 
	 * @param a 直線を（ax + by + c = 0）で表す場合のaです。
	 * @param b 直線を（ax + by + c = 0）で表す場合のbです。
	 * @param c 直線を（ax + by + c = 0）で表す場合のcです。
	 */	
	public function Line( a:Number, b:Number, c:Number ){
		this._a	= a;
		this._b	= b;
		this._c	= c;
 
		this._update();
	}
 
 
	/**
	 * 直線を（ax + by + c = 0）で表す場合のaです。 
	 * @return ax + by + c = 0 の a です。
	 */		
	public function get a():Number{
		return this._a;
	}
	public function set a(n:Number):void{
		this._a = n;
		this._update();
	}
	private var _a:Number;
 
}

コメントはHTMLタグが使える。
参考:一般に使用される HTML エレメントの一覧

ASDocを書き出した時に改行くらい無いと読みづらいものあるので<p>タグは良く使う。
<br>はうまく利かない気がする。あと<a>タグも使えるので参考がある時は記述しておきますね。
コメントを勢いで書くとよく失敗するのが特殊文字。参考の下にある実体参照は注意した方がいい。< > &みたいなHTMLオーサでもよく使うものはすぐ気づいたのだけど、@（アットマーク）とか*（アスタリスク）ってあまり実体参照で使わないと思うので。これがあると書き出しの時エラーになります。

@ = @
* = ~~ （実体参照じゃないけど、ASDoc書式ではチルダ二つで書く）

コメントの記述はこの位にしてASDocの書き出し方。
Flex SDKとターミナルを使います。
FlashDevelop環境ならGUIからいけるっぽいが、自分はMac環境。Mac版作って欲しい。
なのでここからターミナルの操作要点になります。（自分はこの使い方をいつも忘れるのでこっちの方が重要メモ）

ターミナルを立ち上げたら、asdocの実行ファイルディレクトリに移動します。実行ファイルはFlex SDKのbinディレクトリの中にある。コマンドラインを見ると気分が悪くなる僕みたいな人向けの移動する方法。

ターミナルにcd を入力してbinフォルダをドロップ。

次にコマンドを入力します。
参考: ASDoc ツールの実行
コマンドオプションが沢山ありますが必要に応じて指定します。
僕は書き出すファイルをまとめて-doc-sourcesを指定するだけで書き出してます。

まず、asdocを指定する。./を忘れないように注意。

./asdoc

Flex SDKのバージョンによりますが、FlashPlayer10以降のクラスが含まれる場合（Matrix3DとかVector3Dとか）-target-player オプションを入れます。
参考:Flex Builder 3をFlash Player 10に対応させる

./asdoc -target-player=10.0.12

ライブラリにSWCを使っている場合（Progressionとか）、-library-path オプションを入力してSWCファイルのディレクトリを指定します。これもフォルダドロップでOK。

./asdoc -target-player=10.0.12 -library-path /Users/name/project/libs/

書き出したいディレクトリを-doc-sourcesで指定します。フォルダドロップでOK。

./asdoc -target-player=10.0.12 -library-path /Users/name/project/libs/ -doc-sources /Users/name/project/src/jp/nipx/

これを実行すればbinの中にasdoc-outputフォルダが生成され中にASDocが入っています。

知っておくと便利そうなターミナル操作
Control + A　行頭へ移動
Control + E　行末へ移動
Control + U　カーソルより左の文字をすべて消去
Control + W　カーソルより左の文字を単語単位で消去
Control + K　カーソルより右の文字をすべて消去
（ターミナルの設定 > キーボード > メタキーとしてOptionキーを使用にチェックを入れて）
Option + B　単語単位で左に移動
Option + F　単語単位で右に移動

ところで世に配布されているありがたいライブラリなんかは、間違いなく整然としたコメントがつけられています。
数式と文章って真逆なようでそうでもないものだと思う。わかりやすいソースはわかりやすい言葉で説明できるものだと思いました。

Flash

2BLOG