ASDoc in MXML - Functional and Design Specification

Summary and Background

Currently there is no way for users to add documentation to components defined in mxml files. The asdoc tool doesn't read the comments in mxml files. Increasingly more components in the flex framework are being written in mxml.

Adding support for mxml in the asdoc tool would help developers to generate documentation for their components.

Several customer have also added requests in JIRA to support class level comments in mxml files.

Usage Scenarios

Jane is a component developer and provides swc files to her customers. Her customers want api documentation in order to easily use the components, the asdoc tool doesn't support documentation for the components written in mxml. Using the new version of asdoc tool she would be able to generate documentation for mxml components.

Detailed Description

Asdoc comment

To specify comments for asdoc generation in mxml file, the syntax that needs to be followed is

The — (3) dashes following the <! are required, else the comment will be ignored by the asdoc tool.

Components and Class level Comment

Comments for components defined inside mxml or for class level comments must be placed before the
component or the root tag respectively. Else will be ignored.

<?xml version="1.0"?>
<!-- Standard MXML comment: events\myComponents\MyButton.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="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >

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

        <!--- 
         This comment doesn't belong to any component and will be ignored
        --> 
</mx:VBox>

Language Elements

Language Elements are elements like <Script> or <Metadata>

Asdoc comments preceding such element will be ignored.

Elements (properties/methods/styles/effect/event) defined inside such element will need to follow the /** comment */ syntax.

<?xml version="1.0"?>
<!-- Standard MXML comment: events\myComponents\MyButton.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="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
       <!--- 
         Comment for language element - this comment will be ignored.
        --> 
        <Script>
		<![CDATA[
			import flash.events.Event;

			/** 
			 * For a method in an &lt;mx:Script&gt; block,
			 * same rules as in an AS file.
			 *
			 *  @eventType myEvents.EnableChangeEvent
			 */
			private function handleCloseEventInternal(eventObj:Event):void {
				dispatchEvent(eventObj);
			}   
		]]>
	</Script>

	<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")]
	     ]]>
	</Metadata>
</mx:VBox>

Comments before Definition, Library, and Private tag will be ignored. Also comments inside the private block will not be processed.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" width="900" height="700">
	<!--- Comment will be ignored --->
	<Library>
		<!--- Comment will be IGNORED -->
		<Definition name="BlueRect">
			<Group>
					<Rect width="200" height="200">
						<fill>
							<SolidColor color="#0000FF" />
						</fill>
					</Rect>

			</Group>
		</Definition>
	</Library>
	<Graphic>	
	        	<BlueRect width="100" height="200"/>
		        <BlueRect />
	</Graphic>
        <!--- comment will be ignored -->	
	<Private>
		<!--- Design-time metadata  - comment will be ignored -->
		<foo>author</foo>
		<bar>4.0.0</bar>
	</Private>
</mx:Application>

Regular comment

To specify regular comments in mxml file, the syntax that needs to be followed is

These comments will be ignored while scanning the mxml files.

<?xml version="1.0"?>
<!-- Standard MXML comment: events\myComponents\MyButton.mxml -->
<!-- 
	This is a regular comment and will not be included in generated asdoc.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >

        <!-- 
         Comment for button - this is also a regular comment and will be ignored.
        --> 
	<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>

API Description

B Features

Some metadata tags may requires special handling. These would be treated as B feature. The tags which require special handing are ~~[Bindable]~~, [Exclude]. There may be others, but during prototyping I found the following to work out of the box [ExcludeClass], [Deprecated], [DefaultProperty], [Effect], [Event], [Style]

Support for new metadata [SkinState] introduced in gumbo will be treated as B feature.

Since [Bindable] is widely used - it will not be a B feature.

Examples and Usage

Here are some examples of how users would be able to add asdoc comments in mxml files.

Comments should always be in one single comment block. If comments is spread across multiple blocks the last block will only be used

<?xml version="1.0"?>
<!-- Standard MXML comment: events\myComponents\MyButton.mxml -->
<!--- 
	First class level comment - this will not be picked because there is one more comment 
between this an the component declaration. LAST one WINS.
-->
<!--- 
	Second class level comment for the component. Because this is last - it WINS

	@see mx.container.VBox
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
        <Script>
		<![CDATA[
			import flash.events.Event;

			/** 
			 * For a method in an &lt;mx:Script&gt; block,
			 * same rules as in an AS file.
			 *
			 *  @eventType myEvents.EnableChangeEvent
			 */
			private function handleCloseEventInternal(eventObj:Event):void {
				dispatchEvent(eventObj);
			}   
		]]>
	</Script>
</mx:VBox>

Special Class level Comments

Following is the example for a mxml component which also implements an interface. This should result in the "Implements foo.Bar" in the class header.

<?xml version="1.0"?>
<!--- 
	This is a class level comment.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" implements="foo.Bar">
	<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>

Following is the example for a mxml component which is deprecated. This should result in the "Deprecated NewComp" in the class header.

<?xml version="1.0"?>
<!--- 
	This is a class level comment.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
	<mx:Metadata>
		[Deprecated("NewComp")]
	</mx:Metadata>
	<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>

Following is the example for a mxml component which is excluded. This should result in the class getting excluded from the documentation.

<?xml version="1.0"?>
<!--- 
	This is a class level comment.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
	<mx:Metadata>
		[ExcludeClass]
	</mx:Metadata>
	<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>

Inline mxml components

Any inline mxml components must have the id property in order to the comment to be processed.

<?xml version="1.0"?>
<!--- 
	This is a class level comment.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
	<!---
            Comment for button - will not be processed because there is no id for button.
        -->
	<mx:Button label="This button has comment"/>
</mx:VBox>

Any inline mxml components has an id property but no comment. It should still appear in the class documentation.

<?xml version="1.0"?>
<!--- 
	This is a class level comment.
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >
	<mx:Button id="myButtonId" label="This button has comment"/>
</mx:VBox>

Additional Implementation Details

Enter implementation/design details for the feature here. This section may be updated after the spec signs off.

Compiler Work

Currently comments are totally ignored while parsing a mxml file. For this feature the comments will have to be considered during mxml parsing. Also in case of actionscript, the actionscript parser goes through all the tokens so it is able to handle special asdoc tags like @see, @inheritDoc, etc.

During mxml parsing when a comment is encountered it will have to be parsed again for the special tags.

The comment will need to be attached to the following element node so that during implementation generation it can be converted to a comment node and attached to syntax tree in the appropriate place.

Web Tier Compiler Impact

No changes are expected to the Flex Web Tier compiler. No changes should apply to the OEM Compiler API as a result of these changes.

Flex Feature Dependencies

None.

Backwards Compatibility

No compatibility related changes are expected.

Syntax changes

No syntax change for writing mxml files. Only syntax change is the new comment syntax introduced in this feature.

Warnings/Deprecation

This feature does not introduce any new warnings/deprecation.

Accessibility

There are no expected changes to accessibility with this feature.

Performance

We need to keep an eye for any performance impact that may occur due to additional parsing of comments. If there is any significant impact then we can make sure that comments are only parsed when mxml parsing is invoked via asdoc. Because currently no one except for asdoc cares about comments.