Documenting MXML files

An MXML file contains several types of elements, including MXML code, ActionScript code in <fx:Script> blocks, and metadata tags. The ASDoc tool supports all these element types so that you can generate ASDoc content for MXML files just as you can for ActionScript classes.

MXML files correspond to ActionScript classes where the superclass corresponds to the first tag in the MXML file. For an application file, that tag is the <s:Application> tag and therefore an MXML application file appears in the ASDoc output as a subclass of the Application class.

Documenting MXML elements

Use the following syntax to specify an ASDoc comment in an MXML file for an element defined in MXML:
<!--- 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:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <!--- 
        Comment for button
     --> 
    <s:Button id="myButton" label="This button has a comment"/>
</mx:VBox>

In this example, the first comment is a standard XML comment 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.

A leading dash at the beginning of each comment line, and any whitespace characters before the dash, are ignored, as the following example shows: 
<!--- 
    - Comment for my class 
    - which is implemented as mxml 
-->
If you copy a comment from an ActionScript file that uses the /**, *, and **/ characters, those characters are also ignored, as the following example shows: 
<!--- 
    /** 
     * Comment for my class 
     * which is implemented as mxml 
     */ 
--> 
<!--- 
    * Comment for my class 
    * which is implemented as mxml 
-->

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.

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 element 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:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <!--- 
        Comment for first button appears in the output.
     --> 
    <s:Button id="myButton" label="This button has a comment"/>

    <s:Button id="myButton2" 
        label="Has id but no comment so appears in output"/>

    <!--- 
        Comment for button with no id is ignored by ASDoc. 
     --> 
    <s:Button label="This button has no id"/>
</mx:VBox>

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

Documenting ActionScript in <fx:Script> blocks

Insert ASDoc comments for ActionScript code in the <fx:Script> block by using the same syntax as you use 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:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">
    <!--- 
        Comment for language element - this comment will be ignored.
    --> 
    <fx:Script>
        <![CDATA[
            import flash.events.MouseEvent;

            /** 
             * For a method in an &lt;Script&gt; block,
             * same rules as in an AS file.
             *
             * @param eventObj The event object.
             */
            public function handleClickEvent(eventObj:MouseEvent):void {
                dispatchEvent(eventObj);
            }   
            
            /** 
             * For a property in an &lt;Script&gt; block,
             * same rules as in an AS file.
             */
            public var myString:String = new String();
            
        ]]>
    </fx:Script>

    <!--- 
        Comment for first button appears in the output.
     --> 
    <s:Button id="myButton" label="This button has a comment"
        click="handleClickEvent(event);"/>

    <s:Button id="myButton2" 
        label="Has id but no comment so appears in output"/>

    <!--- 
        Comment for button with no id is ignored by ASDoc. 
     --> 
    <s:Button label="This button has no id"/>
</mx:VBox>

Documenting MXML declarations

You can add ASDoc comments to <fx:Declaration> blocks in MXML, as the following example shows:
<fx:Declarations> 
    <!--- 
        Specifies the skin for the first button on the ButtonBar. 
        @default spark.skins.default.ButtonBarFirstButtonSkin 
    --> 
    <fx:Component id="firstButton"> 
        <s:ButtonBarButton skinClass="spark.skins.default.ButtonBarFirstButtonSkin"          /> 
    </fx:Component> 
</fx:Declarations>

Documenting metadata tags

You can insert ASDoc comments for metadata tags in <fx: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\MyVBoxMetaData.mxml --> 
<!--- 
    The class level comment for the component. 
    This tag supports all ASDoc tags, 
    and does not require a CDATA block. 
--> 
<mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"> 
    <!--- 
        Comment for language element - this comment will be ignored. 
    --> 
    <fx:Script>
        <![CDATA[
            import flash.events.MouseEvent;

            /** 
             * For a method in an &lt;Script&gt; block,
             * same rules as in an AS file.
             *
             * @param eventObj The event object.
             */
            public function handleClickEvent(eventObj:MouseEvent):void {
                dispatchEvent(eventObj);
            }   
            
            /** 
             * For a property in an &lt;Script&gt; block,
             * same rules as in an AS file.
             */
            public var myString:String = new String();
            
        ]]>
    </fx:Script>
 
    <fx: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")] 
         ]]> 
    </fx:Metadata> 
    
    <!--- 
        Comment for first button appears in the output.
     --> 
    <s:Button id="myButton" label="This button has a comment"
        click="handleClickEvent(event);"/>
</mx:VBox>