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

In Flex 3, the styles defined using the [Style] metadata were validated by the flex compiler, but styles defined in css files were not validated..

Flex 4 has multiple themes:

1. Spark: The default theme for Flex 4. It contains the skins for Spark and MX Components
2. Halo: The default theme for MX components (if you set -compatibility-version=3.0.0)

Some style can be valid for only one theme but not the other. So if an app uses such a style(valid for one a specific theme), the style won’t work if the theme is switched. This could lead to confusion. To help avoid such situation the Flex 4 compiler is stricter than then Flex 3 compiler.

Flex 4 compiler now validates the styles against the theme.

So for example, if you have an app like:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
			   xmlns:s="library://ns.adobe.com/flex/spark" 
			   xmlns:mx="library://ns.adobe.com/flex/mx">
	<mx:Button label="Hello World !!" borderColor="#FF0000" />	
</s:Application>

Compiling it with the Flex 4 will generate an error like: Error: The style ‘borderColor’ is only supported by type ‘mx.controls.Button’ with the theme(s) ‘halo’.

If however, you had specified the “borderStyle” using an external css file or the <Style> block , for example:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
			   xmlns:s="library://ns.adobe.com/flex/spark" 
			   xmlns:mx="library://ns.adobe.com/flex/mx">
	<fx:Style>
		@namespace mx "library://ns.adobe.com/flex/mx";
 
		mx|Button#buttonId
		{
			borderColor: #FFFF00;
		}
	</fx:Style>
	<mx:Button label="Hello" id="buttonId" /><mx:Button label="World" />		
</s:Application>

Compiling it with the Flex 4 would generate a warning like: Warning: The style ‘borderColor’ is only supported by type ‘mx.controls.Button’ with the theme(s) ‘halo’.

So the rule is “error if invalid style specified inline”, and “warning if invalid style is specified using css/<Style> block”

The recommended way of resolving these warnings/errors is to update the code.

But there may be situations where you would want to re-use some of the components written for your flex 3 apps into the flex 4 apps. If for some reason you can not update those components, you can make use of the newly introduced compiler switches (and buy yourself some time)

The new switches are:

1. -report-invalid-styles-as-warnings: this can be used if your app specified styles inline, and those styles are not valid for the current theme. The default value for this is false, and setting it to true will enables reporting of invalid styles as warnings.
2. show-invalid-css-property-warnings: this can be used if you app specified styles using the css files/<Style> block, and those styles are not valid for the current theme. The default value for this is false, and this switch can be used to toggle whether invalid css property warnings are reported.

You can download the latest nightly builds for Flex 4 from http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4

The nightly builds for Flex SDK 4 now contain a new tool called swcdepends which can be used to analyze the dependencies between SWC files. This tool can be found under the bin folder of the SDK and the latest nightly builds for Flex SDK 4 is available at http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4

Types of Dependencies

There can be four types of dependencies between two action script classes.

• expression – e
• inheritance – i
• namespace – n
• signature – s

Using swcdepends

swcdepends can be used from command line like mxmlc or compc but it also introduces few new options.

If you run the swcdepends without any options then it will display the dependencies for the SWCs present in the Flex SDK. Starting with the ones which have the least dependencies on other SWCs.

But you can also use various options in swcdepends to filter or expand the data you are interested in. Some of them are:

-show-swcs
-show-swcs expects a list of SWCs for which you want to see the dependency info. For example if you run:
$ ./swcdepends -show-swcs framework.swc spark.swc

It will display:

sdk\frameworks\libs\framework.swc:
        sdk\frameworks\libs\player\10\playerglobal.swc
sdk\frameworks\libs\spark.swc:
        sdk\frameworks\libs\textLayout.swc
        sdk\frameworks\libs\framework.swc
        sdk\frameworks\libs\player\10\playerglobal.swc

Notice that it first lists the SWC for which the analysis is requested and then the dependencies are listed (dependencies are indented)

-show-external-classes
-show-external-classes=true will also display the names of classes which are found as dependencies. For example if you run:
$ ./swcdepends -show-swcs framework.swc -show-external-classes=true

It will show output like:

sdk\frameworks\libs\framework.swc:
        sdk\frameworks\libs\player\10\playerglobal.swc
                flash.utils:Dictionary
                flash.events:MouseEvent
                flash.text:TextFieldAutoSize
                flash.xml:XMLDocument
                Class
                Date
                flash.utils:Timer
                .....

-show-types
-show-types=true will also show the type of dependency next to the class. For example if you run:
$ ./swcdepends -show-swcs framework.swc -show-external-classes=true -show-types=true

It will show output like:

sdk\frameworks\libs\framework.swc:
        sdk\frameworks\libs\player\10\playerglobal.swc
                flash.utils:Dictionary  s e
                flash.events:MouseEvent i s e
                flash.text:TextFieldAutoSize    e
                flash.xml:XMLDocument   s e
                Class   e
                Date    s e
                flash.utils:Timer       s e
                .....

Also when -show-types=true is specified -show-external-classes=true is not required.

-types
-types expects the list the type that should be displayed, so this option can be used to filter the information based on types. The following command:
$ ./swcdepends -show-swcs framework.swc -show-types=true -types=i,s

will display:

sdk\frameworks\libs\framework.swc:
        sdk\frameworks\libs\player\10\playerglobal.swc
                flash.utils:Dictionary  s
                flash.events:MouseEvent i s
                flash.xml:XMLDocument   s
                flash.system:LoaderContext      s
                flash.geom:Point        s
                Date    s
                ....

So it will filter out the dependencies of type expression and namespace.

-minimize-dependency-set
-minimize-dependency-set is true by default and it narrows the results to filter out a SWC, if the scripts resolved in the SWC are subset of the scripts resolved in another dependent SWC

So if you run
$ ./swcdepends -show-swcs spark.swc

It doesn’t show you flex.swc, because flex.swc is a subset of framework.swc and everything if flex.swc is already present in framework.swc. But if you want you can always see more info using:

$ ./swcdepends -show-swcs spark.swc -minimize-dependency-set=false

Hopefully this tool will provide useful info regarding how SWCs are related to each other. If you run into any bugs, feel free to log them at http://bugs.adobe.com/flex