ASDocのよくある記述ミス4個+2個

ASDoc便利ですよね。でも、いざ書き出す段になってよくわからないエラーで困ることもよくあります。「昨日までは問題なかったのに」、「swfファイルはちゃんと生成できているのに」なんてことも。
よくある記述ミス4個を紹介します。

なんで、4個かって言うと、さっき2時間つぶした3個と、おととい2時間つぶした1個だから!!
よくあるよくある!
忘れないように!

ダメな例

例えば、次のコードはコンパイルはできるのでswf生成は可能ですが、ASDocの生成はできません。
ちなみに、swc化もできません。Fat SWCだったからかも。
[sourcecode language=”as3″]
package jp.mztm {
import jp.mztm.Foo;
public class Boo {
public function Boo() { };

/**
* 兄弟の名前を返します。
* Vector.<String>なのでstringであることが保障されています。
* この値で次の例のようにクエリー生成をします。
* brother.php?name0=foo&name1=woo
* @return 兄弟の名前
*/
public function getBrother():Vector.<String> {
return Vector.<String>(["foo","woo"]);
}

}
}
[/sourcecode]

エラー1:使ってないimportはダメ!

エラー文:

E:\ASDocTest\src\jp\mztm\Boo.as(2): col: 16 エラー: 定義 jp.mztm:Foo が見つかりません。
import jp.mztm.Foo;
^

理由(推測だけど):
このクラスでjp.mztm.Fooを使ってないから。
実際にはこのクラスが存在していても、使わないクラスがimportされているとだめみたいです。

エラー2:@returnの後に全角スペースが入っちゃダメ!

エラー文:

[Fatal Error] toplevel.xml:51:8: エレメント型 “return” の後には、属性指定 “>” または “/>” が必要です。
org.xml.sax.SAXParseException: エレメント型 “return” の後には、属性指定 “>” または “/>” が必要です。
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)
at flex2.compiler.asdoc.AsDocHelper.createTopLevelClasses(AsDocHelper.java:66)
at flex2.compiler.asdoc.AsDocAPI.createTopLevelClassesXML(AsDocAPI.java:401)
at flex2.tools.ASDoc.asdoc(ASDoc.java:94)
at flex2.tools.ASDoc.main(ASDoc.java:35)
エラー: toplevel.xml を作成できませんでした : エレメント型 “return” の後には、属性指定 “>” または “/>” が必要です。

理由(推測だけど):
@returnの直後は半角スペースを置かないといけないみたい。
FlashDevelopだと、returnのところが彩度が高くなって目立つんだけどね。
コンパイルできるからって、見ない振りしちゃダメです。

エラー3:&は実体参照にすること!

エラー文:

[Fatal Error] :9:31: エンティティ “name1” への参照の終了は、’;’ 区切り記号である必要があります。
適格な形式でないテキストが検出されました。詳細については、E:\ASDoc\validation_errors.log を参照してください。
Source file E:\ASDocTest\ASDoc\tempdita\packages.dita does not exist

理由(推測だけど):
ASDocはhtml化作業なので、実体参照にしないとだめみたい。

エラー4:<String>は実体参照にすること!

エラー文:

[Fatal Error] :7:6: エレメント型 “String” は対応する終了タグ “</String>” で終了する必要があります。
適格な形式でないテキストが検出されました。詳細については、E:\ASDocTest\ASDoc\validation_errors.log を参照してください。
Source file E:\ASDocTest\ASDoc\tempdita\packages.dita does not exist

理由(推測だけど):
ASDocはhtml化作業なので、実体参照にしないとだめみたい。
まあ、エラー3と同じ理由なんだけど、エラー文が違うので分けました。

改善例

そんなわけで、ASDocの生成が可能になるコードは次です。
[sourcecode language=”as3″]
package jp.mztm {
//import jp.mztm.Foo;
public class Boo {
public function Boo() { };

/**
* 兄弟の名前を返します。
* Vector.&amp;lt;String&amp;gt;なのでstringであることが保障されています。
* この値で次の例のようにクエリー生成をします。
* brother.php?name0=foo&amp;amp;name1=woo
* @return 兄弟の名前
*/
public function getBrother():Vector.&lt;String&gt; {
return Vector.&lt;String&gt;([&quot;foo&quot;,&quot;woo&quot;]);
}

}
}
[/sourcecode]

そんなわけで、お疲れ様でした。

以下、2011/12/17追記
ダメな例
[sourcecode language=”as3″]
for (var i:int = 0; i < n; i++)
{
}
[/sourcecode]

エラー5:比較演算子の<も実体参照にすること!

エラー文:

[Fatal Error] :53:27: エレメントの内容は、整形式の文字データまたはマークアップで構成する必要があります。
適格な形式でないテキストが検出されました。詳細については、E:\ASDocTest\ASDoc\validation_errors.log を参照してください。
Source file E:\ASDocTest\ASDoc\tempdita\packages.dita does not exist

理由(推測だけど):
ASDocはhtml化作業なので、実体参照にしないとだめみたい。
まあ、エラー3、4と同じ理由なんだけど、エラー文が違うので分けました。

[sourcecode language=”as3″]
for (var i:int = 0; i &lt; n; i++)
{
}
[/sourcecode]

以下、2012/5/13追記
ダメな例
[sourcecode language=”as3″]
* @author umhr umehara@example.com
* @version 0.1
[/sourcecode]

エラー6:@に気をつけろ!

エラー文:

[Fatal Error] toplevel.xml:514:13: エレメント型 “example.com” の後には、属性指定 “>” または “/>” が必要です。
org.xml.sax.SAXParseException: エレメント型 “example.com” の後には、属性指定 “>” または “/>” が必要です。
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)
at flex2.compiler.asdoc.AsDocHelper.createTopLevelClasses(AsDocHelper.java:66)
at flex2.compiler.asdoc.AsDocAPI.createTopLevelClassesXML(AsDocAPI.java:401)
at flex2.tools.ASDoc.asdoc(ASDoc.java:94)
at flex2.tools.ASDoc.main(ASDoc.java:35)
エラー: toplevel.xml を作成できませんでした : エレメント型 “example.com” の後には、属性指定 “>” または “/>” が必要です。

理由(推測だけど):
メールアドレスの部分の@がだめみたい。@によるコマンドとかぶるからだと思う。コマンドとは異なる行に記入したら、通った。
[sourcecode language=”as3″]
* @author umhr umehara_atmark_example.com
* @version 0.1
* umehara_atmark_example.com is umehara@example.com
[/sourcecode]