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:
<?xml version="1.0"?>
<!-- asdoc\MyVBox.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for button
-->
<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>
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:
flex_dir/bin>asdoc -doc-sources C:\myApp\myMXMLFiles\MyVBox.mxml -output framework-asdoc
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:
<?xml version="1.0"?>
<!-- asdoc\MyVBoxComplex.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for language element - this comment will be ignored.
-->
<mx:Script>
<![CDATA[
import flash.events.Event;
/**
* For a method in an <mx:Script> block,
* same rules as in an AS file.
* @eventType myEvents.EnableChangeEvent
*/
private function handleCloseEventInternal(eventObj:Event):void {
dispatchEvent(eventObj);
}
]]>
</mx:Script>
<mx:Metadata>
<![CDATA[
/**
* Defines the default style of selected text.
*/
[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]
/**
* The component dispatches the darken event
* when the darken property changes.
* @eventType flash.events.Event
*/
[Event(name="darken", type="flash.events.Event")]
/**
* Played when the component darkens.
*/
[Effect(name="darkenEffect", event="darken")]
]]>
</mx:Metadata>
</mx:VBox>
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.
