FlashLit.

ASDoc now works with Flex MXML files

The new Flex 4 SDK is coming along quite nicely over at opensource.adobe.com. All you documentation geeks (there are some of you out there, right?) will be interested in the new ASDoc in MXML feature.

In the past the ASDoc engine could read comments from ActionScript source files, but not from MXML files. That left some big holes in the docs for Flex-based applications.

The new ASDoc engine reads MXML comments and treats them just like ActionScript comment blocks.

Here's an example of how to comment your MXML files:

<?xml version="1.0"?>
<!--- 
   This is the class level comment for the component. 
   This comment supports all ASDoc tags.

   @see mx.container.VBox
-->
<mx:VBox>

 <mx:Script>
  <![CDATA[
  import flash.events.Event;

  /** 
   * For methods, properties, and metadata tags in a Script block,
   * the same commenting rules apply as in an AS file.
   *
   * @eventType com.mydomain.events.EnableChangeEvent
   */
  private function handleChangeEvent(eventObj:Event):void 
  {
   dispatchEvent(eventObj);
  } 
  ]]>
 </mx:Script>

 <!--- 
   This comment describes the following button.
 --> 
 <mx:Button id="awesomeButton" label="Awesome"/>

</mx:VBox>

Note that the XML comment block must start with 3 dashes, not 2 dashes for it to be recognized by ASDoc. For example, this comment block will be processed:

<!--- ASDoc-friendly comment. -->

But this comment block will be ignored:

<!-- Traditional XML comment with 2 dashes, ignored by ASDoc. -->

Have a look at the detailed ASDoc in MXML specification to see more examples.

The good news is that you don't have to wait for the official Flex 4 release to use the new version of ASDoc. It's already available for testing (please let us know if you find any bugs!). Just download a recent nightly build of the Adobe Flex 4 SDK from the Gumbo downloads page. You will find the latest asdoc executable in the bin/ folder.

ActionScript 3.0 Coding Standards

As part of the open source release of the Adobe Flex 3 SDK, Adobe has also posted the ActionScript 3.0 Coding Conventions that the engineers used while developing the framework.

It's been hard to find a good set of AS3 coding standards in the past but this fits the bill. It's pretty thorough even though there are a few sections still marked TBD. It covers naming standards, language usage, file organization, and code formatting.

The standards all seem pretty reasonable too, unlike some other standards documents I've seen elsewhere. I'd say it's about a 95% match with my personal AS3 coding preferences.

Even if you don't agree with all the standards, this is a great starting point for any project team that's embarking on a big Flex, Flash, or ActionScript project. You can just use the Adobe standards as a baseline and tweak as necessary.

Getting ASDoc to recognize Adobe AIR classes

Now that AIR 1.0 is official, some people are having trouble getting the ASDoc utility that ships with Flex Builder 3 to recognize the new AIR classes. Here's a quick way to do it.

Use the -library-path option on the ASDoc command line to include the folder that contains the airframework.swc and airglobal.swc files. For example:

asdoc -source-path . -doc-classes myComponents.MyFileManager  -library-path+=..\frameworks\libs\air

Notice the += after in the -library-path value. That appends the location of the AIR SWC files to the default list, which includes the Flex Framework SWCs.

Of course you will also need to change the path to the \frameworks\libs\air folder relative to the location from which the asdoc utility is running.

The simplest Apollo web browser

It's official. Apollo Alpha 1 has launched!

Before you jump too far into Apollo coding, have a scan through the online Apollo docs and avail yourself of the freely downloadable PDF of the Apollo for Adobe Flex Developers Pocket Guide.

One of the coolest Apollo features is the new HTML rendering control and its Flex framework sibling, the HTML component. This post would feel naked without some kind of code snippet, so here's a super-simple but functional web browser in just three lines of code (or a few more if you count line breaks and closing tags :) ).

<?xml version="1.0" encoding="utf-8"?>
<mx:ApolloApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
   layout="vertical">

   <mx:TextInput id="urlTxt" 
      width="100%" 
      enter="html.location=urlTxt.text;"
      text="http://www.adobe.com/go/apollo" />

   <mx:HTML id="html" 
      width="100%" height="100%"
      location="http://www.adobe.com/go/apollo" />

</mx:ApolloApplication>

That example creates a single text field for entering a URL and an HTML component for loading the HTML and JavaScript content. When you press the Enter key in the text field, it sets the location property of the HTML control to the value of the text field, and then web page loads and displays.

You'll notice that most of the buttons and controls you expect to see in a real web browser -- Back and Next buttons, and so on -- don't come pre-packaged with the HTML component. We'll deal with that issue in the next post.

Apollo Camp in progress

We're midway through the Apollo Camp event here at the Adobe office in San Francisco. The level of customer interest is high. It's a very high-energy event, in spite of the late hour on a (mostly) work day.

It's great to see real-time blog posts popping up during the event. Ryan Stewart, Renaun Erickson, Josh Tynjala, Lee Brimelow, Mims Wright and others have already published posted great descriptions of the lead up to the event, the early talks (including Kevin Lynch's keynote), and of course the schwag. (It's great to see the the Apollo for Adobe Flex Developers Pocket Guide was part of the goodie bag. That way at least a few people will read it. :) )