ASDoc – wading through the errors

ASDoc is a nightmare. What should have been a simple task turned into a day of trawling the net trying to find the cause of the seemingly endless errors preventing me from running it. Eventually I got it working so here’s a short post explaining the pitfalls I faced.

  • Include the Flex libraries in your -library-path argument (i.e. flex.swc, rpc.swc, framework.swc, utilities.swc). Without this I was getting errors from asdoc not being able to find some of the standard classes.
  • Check your code! Some of the errors I was getting were actually problems that just weren’t throwing errors (some of my event dispatching classes were not extending EventDispatcher, this threw lots of errors whenever asdoc encountered dispatchEvent )
  • Give your -source-path as the root of your application but use -doc-sources to list only those folders you actually want documenting

For reference here is my very simple ANT script for generating my ASDocs:


<project name="ASDoc Build Script" default="main" >

<!--
 Read in the properties file which contains the locations
 for all paths referred to here
 -->
 <property file="asdoc.properties" />

<!--
 Main Target:
 Cleans and compiles ASDocs with a log
 -->
 <target name="main" depends="clean, log, create-docs" />

<!--
 Delete and recreate the asdoc output directory
 -->
 <target name="clean" >
 <delete dir="${output.dir}" />
 <mkdir dir="${output.dir}" />
 </target>

<!--
 Run asdoc.exe on the source documents passing all required
 parameters to asdoc
 -->
 <target name="create-docs" >
 <exec executable="${asdoc.exe}" failonerror="true" >
 <arg line="-source-path '${root_src}' " />
 <arg line="-doc-sources '${framework_src}' '${actionscripts_src}' " />
 <arg line="-library-path '${irmds_library.dir}' '${flex_library.dir}'" />

<arg line="-main-title '${main.title}'" />
 <arg line="-window-title '${window.title}'" />
 <arg line="-output '${output.dir}'" />
 </exec>
 </target>

<!--
 Write out a log file
 -->
 <target name="log" >
 <record name="${output.dir}/asdoc-log.txt" action="start" append="true" />
 </target>
</project>

Advertisements

Applying focus to Flex application on startup

On a recent project we carried out some accessibility testing and one of the problems faced was with keyboard users who couldn’t use a mouse. After loading the application (by typing in the URL in the address bar) the users couldn’t tab to the input fields on the application, focus would never reach the flex app at all. After searching around I eventually found a little code snippet in a comment on Flex Examples.

 private function setApplicationFocus():void{
 navigateToURL(new URLRequest("javascript: document.getElementById(<DOM_ID>).focus();"), "_self");
 focusManager.setFocus();
 }
 

The above is called in the Application object on creationComplete.