Mio Project!

[雑記] ドキュメンテーション・続

ASのAPI仕様書の作成について、自分なりに軽くまとめてみます（ぱ～と２）。

前回は、API仕様書の生成方法だけを説明しましたが、今回はAS3.0ファイルにどういう風に仕様書を書いていくのかを説明します。

クラスのドキュメンテーション

ASDocでは、JavaDocと同様に、「/**」で始まるマルチラインブロックコメントでドキュメンテーションを付けていきます。

クラスのドキュメンテーションを行う際は、クラスの定義の前の行にASDocコメントを追加します。

クラス自体のドキュメンテーション

一番簡略な例から説明します。次のような、メンバーやコンストラクタを一切持っていないクラスに以下のようにドキュメントを付けてみたときに生成されるAPI仕様書は次のようになります。

package net.chsmea.mioproject.sample {
	/**
	 * メンバーもコンストラクタも何もないクラス.
	 */
	public class Hoge {
		// no members and constractor.
	}
}

 

コンストラクタのドキュメンテーション

次に、上のクラスではコンストラクタを省略して記述していましたが、下記のように省略せずにちゃんとコンストラクタを定義した場合、生成されるAPI仕様書は次のようになります。

package net.chsmea.mioproject.sample {
	/**
	 * メンバーもコンストラクタも何もないクラス.
	 */
	public class Hoge {
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			// ここでインスタンスプロパティの初期化などを行う。
		}
	}
}

 

finalサブクラスのドキュメンテーション

あるクラスを継承したfinalクラスを定義した例も置いておきます。下の例は、Spriteクラスを継承したfinalクラスHogeのAPI仕様書の出力例です。

package net.chsmea.mioproject.sample {
	import flash.display.Sprite;
	/**
	 * Spriteクラスを継承したfinalなクラス.
	 */
	public final class Hoge extends Sprite {
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			// ここでインスタンスプロパティの初期化などを行う。
		}
	}
}

 

クラスのドキュメンテーションの要旨表記と詳細表記

つぎに、クラスのドキュメンテーション時のサマリー(Summary)と、段落の設定ですが、以下の例のようにすればOKです。
　そして、他のクラスのドキュメンテーションへの参照を促す際には、「@see」タグを使用します。

package net.chsmea.mioproject.sample {
	/**
	 * Hogeクラス (この部分だけが, Summaryとして表示される).
	 * 
	 * 
このHogeクラスは, Fooを継承していて, ～～云々～～～.

	 * ～～～云々～～～.
	 * 
	 * @see Foo Fooクラスについても, 参照してください.
	 */
	public class Hoge extends Foo {
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			// ここでインスタンスプロパティの初期化などを行う。
		}
	}
}

package net.chsmea.mioproject.sample {
	/**
	 * Fooクラス.
	 */
	public class Foo {
		
	}
}

 

 

プロパティのドキュメンテーション

次に、プロパティのドキュメンテーション方法について軽くまとめます。

アクセス修飾子がそれぞれ異なるプロパティのドキュメンテーション

public / internal / protected / private なプロパティを定義をした際に生成されるAPI仕様書は次のようになります。

package net.chsmea.mioproject.sample {
	/**
	 * Hogeクラス.
	 */
	public class Hoge {
		/**
		 * publicな, ほげ～.
		 */
		public static var pubStrHoge : String = "ほげほげぇ～";
		
		/**
		 * internalな, ほげ～.
		 */
		internal static var innStrHoge : String = "ほげほげ～";
		
		/**
		 * protectedな, ほげ～.
		 */
		protected static var prtStrHoge : String = "ほげぇ～";
		
		/**
		 * privateな, ほげ～.
		 */
		private static var prvStrHoge : String = "ほげ～";
		
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			
		}
	}
}

 

 

上の生成例を見ても分かるように、privateで定義したプロパティは隠蔽化され、API仕様書には出力されません。

プロパティの実装のドキュメンテーション

なお、この隠蔽化されたプロパティにアクセスできるようにする機構である、getter/setterメソッドを定義することにより、privateなプロパティも実装され、API仕様書に出力されるようになります。

ちなみに、getter/setterメソッドは、ASDocではプロパティとして扱われ、メソッドとしてドキュメント化されることはありません。
　また、getter/setterの両方を実装する場合は、setterメソッドの方のASDocコメントには「@private」タグを付けて、ドキュメンテーションの記述の重複を防ぐようにします。

package net.chsmea.mioproject.sample {
	/**
	 * Hogeクラス.
	 */
	public class Hoge {
		// 隠蔽化するインスタンスプロパティを定義
		private var prvStrHoge : String = "ほげ～";
		
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			
		}
		
		// getterメソッドの定義
		/**
		 * ほげ～.
		 * 
		 * @default "ほげ～"
		 */
		public function get prvStrHoge() : String {
			return this.prvStrHoge;
		}
		
		// setterメソッドの定義
		/**
		 * @private
		 */
		public function set prvStrHoge(str : String) : void {
			this.prvStrHoge = str;
		}
	}
}

 

読み取り専用なプロパティの実装のドキュメンテーション

また、getterメソッドだけを使って、次のように、読み取り専用 (read-only) なプロパティを実装することが出来ます。

package net.chsmea.mioproject.sample {
	/**
	 * Hogeクラス.
	 */
	public class Hoge {
		// 隠蔽化する読み取り専用なインスタンスプロパティを定義
		private var w : int = 58;
		
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			
		}
		
		// getterメソッドの定義
		/**
		 * ほげの重量 (単位は, kg) .
		 * 
		 * @default 58 (kg)
		 */
		public function get weight() : int {
			return this.w;
		}
	}
}

 

 

メソッドのドキュメンテーション

次に、メソッドのドキュメンテーション方法について軽くまとめます。

メソッド特有のドキュメンテーション

基本はクラスのドキュメンテーションの付け方と同じですが、メソッド特有のものとして、次の2つのタグをよく使うことになると思います。
　まず、一つ目として「@param」タグ。これは、メソッドが引数を取る場合に、取る引数の説明を行います。また、注意点として、「@param」タグの記述順序は、メソッドの引数の記述順序に合わせないといけません。
　そして、二つ目として「@return」タグです。名前の通り、返り値の説明を行います。

package net.chsmea.mioproject.sample {
	/**
	 * Hogeクラス.
	 */
	public class Hoge {
		// 隠蔽化するインスタンスプロパティを定義
		private var w : int = 58;
		
		/**
		 * コンストラクタ.
		 */
		public function Hoge() {
			
		}
		
		// getterメソッドの定義
		/**
		 * ほげの重量 (単位は, kg) .
		 * 
		 * @default 58 (kg)
		 */
		public function get weight() : int {
			return this.w;
		}
		
		// setterメソッドの定義
		/**
		 * @private
		 */
		public function set weight(val : int) : void {
			this.w = val;
		}
		
		/**
		 * 重くな～る.
		 * 
		 * @param incWt 増やす重量 (kg)
		 * 
		 * @return 重くなった後の重量 (kg)
		 */
		public function increaseInWeight(incWt : uint = 0) : int {
			this.w += incWt;
			return this.w;
		}
	}
}

 

 

 

かなり説明してきたつもりなのですが、AS3.0のドキュメンテーションについて、まだまだ全く説明しきれてないですね・・・。
　余裕があったら、また続きを作成するかもです。

#####コメント#####

本日のツッコミ

たこ (2009年08月11日(Tue) 06:39)

ドキュメンテーションなんてやったことないですね～。
必要なことなんでしょうけど…＞＜