Updates, new content, and other helpful information from the Flex Documentation Team.

Posts in Category "ASDocs"

Use the ActionScript® 3.0 Reference for the Adobe® Flash® Platform as the API reference for many Adobe products, including Flash Player, AIR, and Flex. The November, 2011, release of the ActionScript Reference (http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/) contains major performance improvements and other new features:

Refresh right-pane only on selection, instead of entire page. This feature improves page-load performance by implementing a right-pane only refresh on selection. This feature improves page-load times in the range of 25-50% (not available in all versions of IE).

Improved linking to Adobe User Guides. Reorganized the See Also sections into three areas – More Examples, Learn More, and Related API Elements. This reorganization makes it easier to find examples and usage information for a class or class element. For example, see the ViewNavigator class.

The Show Packages and Classes option is now the default to address a frequent customer request.

Use the ActionScript® 3.0 Reference as the API reference for many Adobe products, including Flash Player, AIR, Flex, and LiveCycle. To improve searching of the reference in Chrome, install the “ActionScript 3.0 Search” extension:

Context-sensitive language reference Help is not really a new feature in Flash Builder. However, we figured that several people were not aware of the ways in which you can access the ActionScript language reference and ASDoc content from within Flash Builder.

So, this post describes the ways in which you can quickly access the ActionScript API reference and the ASDoc content while writing code.

Display the ActionScript Language Reference in a swift keystroke

The Adobe ActionScript Language Reference is integrated into the MXML and ActionScript editors and lets you quickly view the reference Help for an MXML tag or property, a class, or a Flex framework element.

In the MXML or ActionScript editor, select a Flex framework element (a word in your code) by highlighting or placing the mouse pointer in the word.

To open the relevant ActionScript Language Reference topic directly in the Help viewer, press Shift+F2.

Display ASDoc content in code hints, as a tool tip, and in the ASDoc view

Flash Builder displays ASDoc content in code hints, as a tool tip while hovering over a code element, and in the ASDoc view.

Begin entering a line of code that contains either an MXML or ActionScript class. You can also hover over the class. As you type, ASDoc content for the class displays next to the code hints, as follows:

ASDoc Code Hints

If you hover over a class, just the ASDoc reference summary appears. To display the content in a separate, scrollable window, press F2.The ASDoc content is displayed as follows:

ASDoc Content

When you finish reading the documentation, click outside the ASDoc window to close it.

To display the complete ASDoc content in a dockable ASDoc view in Flash Builder, select Window > Show View > Other, and select ASDoc.A quicker way of displaying the ASDoc view is to press Ctrl+3, type asdoc, and select Views, as follows:

ASDoc view

Note: This feature supports user-generated ASDoc documentation. That is, you can document your custom components by adding ASDoc comments to the code that implements the components. The ASDoc comments are then available as code hints in the MXML and ActionScript editors.
For more information on creating ASDoc comments for your source files, see ASDoc.

Support for a quick search added to the Packages and Classes lists.The quick search lets you filter the content of the Packages and Classes lists as you type. This feature is not supported on IE 7 and IE 8.

When displaying all classes in the Classes list, selecting a class name in the list continues to display all classes.In the previous release, selecting a class name in the Classes list while displaying all classes changed the Classes list to display only the classes in the package of the selected class.

Added a Home link to the top of all pages.The Home link lets you navigate back to the index.html page from anywhere in the reference.

Platform ActionScript Reference – Contains new and updated classes for all Adobe products that feature ActionScript APIs. In particular, it has new Flex classes, such as Spark DataGrid, Image, and Form. If you haven’t used the Platform ASR before, note that you can change the filter settings to control which products and versions you see.

Using Flex – Contains usage information on new Flex SDK features, such as Spark DataGrid, Image, and Form (remember, we have corresponding reference and usage discussions for most Flex features). This book also contains updates and enhancements to existing discussions.

Using Flash Builder – We reorganized this book to clarify the Flash Catalyst, ActionScript, and Flash Professional workflows. In particular, there is new information on implementing two-way designer-developer workflows with Flash Catalyst.

Accessing Data with Flex – There aren’t many changes to this book, although we did update screen shots in the Flash Builder workflows.

And lightning will strike me down if I neglect to highlight the amazing work done by the Flex and Flash Builder Community Help & Learning (aka documentation) team: Stephen Gilson, Matt Horn, Mallika Yelandur, Pam Araki, Rosana Francescato, Janice Campbell, Sunil Bhaskaran, and Helen Li all did a great job bringing this content to fruition. Also we received critical support from Cate de Heer, Denise Green, Brian Rinaldi, my old friend Erick Vera, and my manager, Helen Whelan.

That’s all for now, but my team and I will be updating this site regularly over the next few weeks, so stay tuned.

Six years ago, when I started managing the Flex documentation, we almost immediately started worrying about future proliferation of the ActionScript API content. You see, we were republishing very similar content to a new location for each product and each version. For example, http://livedocs.adobe.com/flex/2/langref, http://livedocs.adobe.com/flex/201/langref, and http://livedocs.adobe.com/flex/3/langref, while they have different Flex content, all have virtually identical content for the flash.* packages.

At that time, we anticipated customers would have trouble locating the ActionScript API content for their product/version and/or google into the wrong version and miss seeing up-to-date information. And this has turned out to be true.

Obviously, the right thing to do is create one version of this content covering all the Adobe products that feature ActionScript APIs. However, it turns out that this is a non-trivial task, given all the products that use ActionScript, including Flex, Flash Pro, LiveCycle, LiveCycle Data Services, Flash Lite, FMS, and ColdFusion.

So I hope everyone realizes just how happy I am to say that we have released the ActionScript 3.0 Platform Reference and that it includes content for all released Adobe products that feature ActionScript APIs.

So when you get a minute, please open and bookmark ActionScript 3.0 Platform Reference. It has an updated look and feel, including content filtering by product, runtime, and version, so you can exclude classes for the products you don’t use.

Stay tuned to this blog and other Adobe Learning Resources blogs for more details on the ActionScript 3.0 Reference for the Adobe Flash Platform and tips on how to get the most out of it.

And remember that we’re running on help.adobe.com these days, and no longer use livedocs.adobe.com.

If you happen to land on a language reference page for an old version, you can use the version pod to navigate to the correct version. The version pod displays towards the top right of each page and you can hide it by clicking the right arrow icon.

In the weeks to come, I hope to write a series of posts that cover the kinds of things our group is doing to improve the overall experience with Adobe learning content.

The Flex ASDoc command-line tool parses one or more ActionScript class definitions and MXML files to generate API language reference documentation for all public and protected methods and properties, and for certain metadata tags. The Gumbo release of Flex adds new features to the ASDoc command-line tool, including support for ASDoc comments in MXML files.

The ASDoc command-line tool is in the bin directory of your Flex Gumbo installation directory.

MXML Comments

The previous release of the ASDc command-line tool processed MXML files as input, but did not support ASDoc comments in the MXML file. In this release, you can now use the following syntax to specify an ASDoc comment in an MXML file:

<!— asdoc comment –>

The comment must contain three dashes following the opening <! characters, and end with two dashes before the closing > character, as the following example shows:

In this example, the first comment is a standard XML comment that is ignored by ASDoc. The second comment precedes the root tag of the component and uses the three dashes to identify it as an ASDoc comment. An ASDoc comment on the root tag is equivalent to the ASDoc comment before an ActionScript class definition. Therefore, the comment appears at the top of the output ASDoc HTML file.

All MXML elements in the file correspond to public properties of the component. The comment before the Button control defines the ASDoc comment for the public property named myButton of type mx.controls.Button.

You can use any ASDoc tags in these comments, including the @see, @copy, @param, @return, and other ASDoc comments.

Specify the input MXML file to the compiler in the same way that you specify an ActionScript file. For example, you can use the -doc-sources option of the compiler to process this file:

The ASDoc command-line tool only processes elements of an MXML file that contain an id attribute. If the MXML element has an id attribute but no comment, the elements appears in the ASDoc output with a blank comment. An MXML element with no id attribute is ignored, even if it is preceded by an ASDoc comment, as the following example shows:

<?xml version="1.0"?>
<!-- asdoc\MyVBoxID.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
@see mx.container.VBox
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for first button appears in the output.
-->
<mx:Button id="myButton" label="This button has comment"/>
<mx:Button id="myButton2" label="This button has no comment"/>
<!---
Comment for button with no id is ignored by ASDoc.
-->
<mx:Button label="This button has no id"/>
</mx:VBox>

You can insert ASDoc comments for metadata tags in the <Script> and <Metadata> blocks in an MXML file. For metadata tags, the ASDoc comments use the same syntax as you us in an ActionScript file. The only requirement is that the ASDoc comments must be within a CDATA block, as the following example shows:

Comments before Definition, Library, and Private tags are ignored. Also comments inside a private block are ignored.

New option to the ASDoc command-line tool

By default, the ASDoc command-line tool halts processing and outputs a failure message when an ASDoc comment in an input file contains invalid HTML code. The tool writes error information to the validation_errors.log file.

This release of the ASDoc command-line tool adds the -lenient option that specifies to complete the compilation even when an HTML error occurs. The ASDoc comment that included the error is omitted from the output and the tool writes error information to the validation_errors.log file, but the remainder of the file or files is processed normally.