Have you tried the latest Flash Builder? If not, the latest beta can be downloaded from http://labs.adobe.com/technologies/flashbuilder4/?sdid=EUHSU

But if you have already tried it, you would have noticed that now ActionScript and MXML editors show ASDoc documentation when you hover over variables/method/class names. See screen shot below:

This means that you can now see the documentation as you are writing code. You can see the method/variable signature or any other documentation associated with any of the class elements. And for all this you don’t need to open the language reference in a separate browser window or search for the documentation.

Behind the scenes Flash Builder pulls this information from the Flex SDK swc files and the ASDoc info is stored in XML files inside the SWC files. For all nightly builds of Flex SDK, the swcs will come with these ASDoc XML files. In case you want to add similar ASDoc XML files to your custom swcs, you can do that too. Currently there is no single command to generate swc with ASDoc XML files, it is done in three simple steps. And the three steps are:

1. Generate SWC
2. Generate doc XML Files using ASDoc tool
3. Update SWC with doc XML fIles

I hope you already know how to generate a swc file. If not, take a look at http://livedocs.adobe.com/flex/3/html/help.html?content=compilers_22.html
In order to generate the doc XML files using ASDoc tool, you will have to run the asdoc tool using -keep-xml=true and -skip-xsl=true
A swc file is a compressed file, so to update it (with doc XML files) you can simply use a zip command.

For reference, you can also look at the build.xml file in the framework project of the Flex SDK. Following is the “doc” target which performs step #2 and #3:

<target name="doc" depends="clean-temp-docs" description="updates framework.swc with asdoc xml">
		<!-- Load the <asdoc> task. We can't do this at the <project> level -->
		<!-- because targets that run before flexTasks.jar gets built would fail. -->
		<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/lib/flexTasks.jar"/>
 
	    <condition property="asdoc.jvm.args" value="-Xmx384m">
	        <os family="windows"/>
	    </condition>
 
	    <condition property="asdoc.jvm.args" value="-Xmx512m">
	        <os family="mac"/>
	    </condition>
 
	    <condition property="asdoc.jvm.args" value="-Xmx512m">
	        <os family="unix"/>
	    </condition>
 
		<!-- Call asdoc to generate dita xml files -->
		<asdoc output="${FLEX_HOME}/tempDoc" lenient="true" failonerror="true" keep-xml="true" skip-xsl="true" fork="true">
		    <compiler.source-path path-element="${basedir}/src"/>
		    <doc-classes class="FrameworkClasses"/>
		    <doc-namespaces uri="http://www.adobe.com/2006/mxml"/>
		    <namespace uri="http://www.adobe.com/2006/mxml" manifest="${basedir}/manifest.xml"/>
		    <jvmarg line="${asdoc.jvm.args}"/>
		</asdoc>
 
		<!-- updates framework.swc with asdoc xml -->
		<zip destfile="${FLEX_HOME}/frameworks/locale/en_US/framework_rb.swc" update="true">
		    <zipfileset dir="${FLEX_HOME}/tempDoc/tempdita" prefix="docs">
			    <include name="*.*"/>
				<exclude name="ASDoc_Config.xml"/>
				<exclude name="overviews.xml"/>
		    </zipfileset>
		</zip>
	</target>

So give it a try, and if you find any bugs you can log them at http://bugs.adobe.com/flex

So you have a lot of packages and you want to add description for all your package for ASDoc? You can use the -packages.package parameter but it can be tedious to repeat the ASDoc command line parameter (-packages.package) for each individual package.

Now you don’t have to repeat the parameter because you can now use the new parameter (-package-description-file) instead.

Using the new parameter (-package-description-file) you can now specify a xml file that contains the description for all your packages.

The format of the file is as follows:

<overviews>
	<packages>
		<package name="package.name1">
			<shortDescription></shortDescription>
			<description></description>
		</package>
	</packages>
</overviews>

Here is a sample file (pkgDescription.xml)

<overviews>
	<packages>
		<package name="mx.core">
			<shortDescription>
			<![CDATA[
				The mx.core package contains the
				base classes and interfaces,
				such as UIComponent, used by Flex.
			]]>
			</shortDescription>
			<description>
			<![CDATA[
				The mx.core package contains the
				base classes and interfaces,
				such as UIComponent, used by Flex.
			]]>
			</description>
		</package>
		<package name="mx.controls">
			<shortDescription>
			<![CDATA[
				The mx.controls package contains
				the Flex user-interface controls.
			]]>
			</shortDescription>
			<description>
			<![CDATA[
				The mx.controls package contains
				the Flex user-interface controls.
			]]>
			</description>
		</package>
	</packages>
</overviews>

Here is how you can use it:

./asdoc -package-description-file=pkgDescription.xml
-doc-classes=mx.controls.Button
-source-path=<sdk root>/frameworks/projects/framework/src

This parameter is available in Flex SDK 4 only. And the nightly build of Flex SDK 4 can be found at http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4 (choose a build after 4.0.0.8245 to use this parameter)

If you work in a team and use Flex, then you definitely use code written by other developers on your team. Wouldn’t it be nice to see the asdoc for their code the same way you see asdoc for the Flex SDK? Well now you no longer have to manually run asdoc, you can now leverage the <asdoc> ant task which is part of the Flex SDK.

The <asdoc> is available in the Flex 4 SDK only (not available in Flex 3). Nightly builds for the Flex 4 sdk can be downloaded from http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4

Here is an sample asdoc target that can be used in ant build file.

<target name="asdocgen">
		<!-- for svn users the flexTasks.jar is
			under <sdk root>/lib -->
		<available property="flexTasksJar"
			value="${sdk.dir}/lib/flexTasks.jar"
			file="${sdk.dir}/lib/flexTasks.jar"/>

		<!-- for sdk package (zip) the flexTasks.jar is
			under <sdk root>/ant/lib -->
		<available property="flexTasksJar"
			value="${sdk.dir}/ant/lib/flexTasks.jar"
			file="${sdk.dir}/ant/lib/flexTasks.jar"/>

	    <property name="FLEX_HOME" value="${sdk.dir}" />	

		<asdoc output="${output.folder}/asdoc-output"
			main-title="My asdoc main title"
			footer="<u>My custom footer.</u>"
			window-title="Custom asdoc documentation"
			left-frameset-width="300"
			failonerror="true" fork="true">

			<packages.package name="com.test"
				description="description for com.test" />

			<!-- top level class to include in asdoc.
				These should be in the source-path (src1, src2) -->
			<doc-classes class="com.test.CustomMain"/>
			<doc-classes class="com.test.Foo"/>

			<!-- generate asdoc for all as/mxml files in the doc-sources -->
			<doc-sources path-element="${basedir}/src3"/>

			<!-- don't try to generate asdoc for
				includeFile.as (its an include file
				and can't be independently compiled -->
			<exclude-sources path-element="${basedir}/src3/includeFile.as"/>

			<!-- source path for asdoc -->
			<compiler.source-path path-element="${basedir}/src1"/>
			<compiler.source-path path-element="${basedir}/src2"/>

			<!-- namespaces to include in asdoc -->
			<doc-namespaces uri="http://www.gauravj.com/blog/"/>

			<!-- namespace declaration for asdoc -->
			<namespace uri="http://www.gauravj.com/blog/"
			manifest="${basedir}/manifest.xml"/>

			<jvmarg line="-Xmx512m"/>
		</asdoc>
	</target>

As you can see it supports all the options of command line asdoc (doc-classes, doc-sources, doc-namespaces, source-path, etc.). So you can now write ant targets for your asdoc generation.

If you face any issues or have any feedback, you can log bugs at http://bugs.adobe.com/flex