asdoc pain

Running asdoc should have been a breeze. Just create an ant task which calls the asdoc executable with the given parameters and voila! Well, it was not.

<target name="compile">
<exec executable="${asdoc}" failonerror="true">
<arg line="-doc-sources ${src.dir}"/>
<arg line="-window-title "My Application""/>
<arg line="-output ${asdoc.output}"/>
</exec>
</target>

The task started by spilling 100 errors similar to:

[exec] ...budgetImport.as(9): col: 1 Error: The public attribute can only be used inside a package.
 [exec]
 [exec] public var importing:Boolean = false;
 [exec] ^
 [exec]
 [exec] ...budgetImport.as(12): col: 1 Error: The public attribute can only be used inside a package.
 [exec]
 [exec] public var dp:Object = new Object();
 [exec] ^
 [exec]
 [exec] ...budgetImport.as(14): col: 10 Error: The public attribute can only be used inside a package.
 [exec] ^
 [exec]
 [exec] Encountered too many errors!

This should not have happened since the compilation worked fine on these classes. After some digging I decided to limit the problem to basics and tried on a few classes from the command line. It was the same problem. Some more parameters tests later I dropped the -doc-sources in favor of -doc-classes. Thus the errors disappeared. This parameter however required all classes to be passed as parameter but the solution used previously to generate SWC’s helped.

I then started to add more classes, mxml files. Bumped again into this:

[exec] Error: ../myAdmin.as and ../myAdmin.mxml can't co-exist in the same directory.

Hmm, I can understand that he does not know which file to associate with the class name so I got back to the -doc-sources parameter to specify each mxml by hand. The resulting task was:

<target name="asdoc">
 <delete dir="${asdoc.output}" />
 <mkdir dir="${asdoc.output}" />
 <fileset id="sources" dir="${src.dir}">
 <include name="all the classes, libraries, etc" />
 </fileset>
 <pathconvert property="classes" pathsep=" " refid="sources">
 <chainedmapper>
 <globmapper from="${basedir}/${src.dir}/*" to="*" handledirsep="true" />
 <mapper type="package" from="*.as" to="*" />
 </chainedmapper>
 </pathconvert>
 <echo message="classes is set to = ${classes}" />
 <fileset id="sources-mxml" dir="${src.dir}">
 <include name="all the .mxml's which have a corresponding .as" />
 <exclude name="everything with problems" />
 </fileset>
 <pathconvert property="doc-mxml-sources" pathsep=" " refid="sources-mxml">
 <chainedmapper>
 <globmapper from="${basedir}/*" to="*" handledirsep="true" />
 </chainedmapper>
 </pathconvert>
 <echo message="mxml-sources is set to = ${doc-mxml-sources}" />
 <exec executable="${FLEX_HOME}/bin/${asdoc}" failonerror="true">
 <!--<arg line="-exclude-dependencies=true"/>
 <arg line="-keep-xml -warnings"/>-->
 <arg line="-doc-classes ${classes}" />
 <arg line="-doc-sources ${doc-mxml-sources}" />
 <arg line="-source-path ${src.dir}" />
 <arg line='-window-title "My app"' />
 <arg line="-output ${asdoc.output}" />
 <arg line="-library-path ${FLEX_HOME}/frameworks/libs -library-path libs" />
 </exec>
 </target>

This worked on most files but sometimes it gave a:

[exec] An unexpected error occurred.
 [exec] Error #1083
 [exec]
 [exec] (Location of error unknown)XSLT Error (javax.xml.transform.TransformerException):
java.io.FileNotFoundException: .../flex/doc/asdoc/toplevel_classes.xml (No such file or directory)

This error came with no extra information on which file caused problems and actually means there is a asdoc tag which the asdoc does not like. There is no other way then to proceed by elimination until you find the cause (thus the reason for the exclude param). Talk about lost hours … (apparently there is a -lenient option in asdoc 4 just for this but I am still on 3)

Finally when everything works you will get the wonderful message:

[exec] Documentation was created in ../flex/doc/asdoc/

Leave a Reply

*