Mio Project!

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

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

ActionScriptに進む前に、他のいくつかの言語におけるドキュメンテーションについておさらい。

C#

C#では、XMLドキュメントコメントを使います。コンパイラ自体にドキュメンテーション用の機構が含まれているので、コンパイル時に「 /doc:file」オプションを引けばドキュメントが生成されます。

using system;
namespace Sample {
	/// <summary>
	///  Mio Class.
	/// </summary>
	public class Mio:Human {
	}
}

詳しくは、 XMLドキュメントコメント (C#プログラミングガイド) 参照。

Java

もちろん、Javadocです。あまりに有名すぎるので、ここでは割愛。

前置きはこのへんにして、ActionScript3.0のドキュメンテーションについて触れていきます。

ActionScript3.0

AS3.0のドキュメンテーションツールとして、「asdoc」が用意されています。ちなみに、AIR (Adobe Integration Runtime)の場合は、「aasdoc」です。

C:\***\> asdoc
設定ファイル "C:\flex_sdk_3\frameworks\flex-config.xml" をロードしています
Adobe ASDoc
Version 3.3.0 build 4852
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.
　
エラー: doc-sources、doc-classes、または doc-namespaces を指定する必要があります。
　
コマンドラインの使用に関する情報については、'asdoc -help' を使用してください。

次のように、コマンドを打てば、カレントディレクトリ以下にある全てのクラスのAPI仕様書がカレントディレクトリに作られます。

C:\***\> asdoc -ds .

ちなみに、「-ds」オプションは、「-doc-sources」オプションのエイリアス名となっています。

API仕様書の名前を変更する際や、作成されるディレクトリ名を変更する際には、次のようにコマンドを打ちます。

C:\***\> asdoc -ds .
              -o asdoc
              -main-title "Mio API Documentation"
              -window-title "Mio API Documentation"

生成されたAPI仕様書は、「-o」(「-output」) オプションで指定した名前のディレクトリ内に生成されます。ちなみに、「-o」に何も引かなかった場合のデフォルト値は、「asdoc-output」になります。
　そのディレクトリ内の「index.html」を開けば、生成されたAPI仕様書を見ることが出来ます。

また、footer（フッター）や、packageのDescriptionを指定するには、次のようにコマンドを打てばOKで、このとき次の図ような作成結果になります。

C:\***\> asdoc -ds .
              -footer "2009 Mio Project All Rights Reserved."
              -package net.chsmea.mioproject.sample "sample classes and interfaces"

・・・今日はここまで。
　また続きます・・・。