Flex SDK Wiki

# 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 <!--- asdoc comment --> 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. <mx:vbox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo"> <mx:button id="myButton" label="This button has comment"> </mx:button></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. <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> <metadata> 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. <mx:application xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" width="900" height="700"> <library> <definition name="BlueRect"> <group> <rect width="200" height="200"> <fill> <solidcolor color="#0000FF"> </solidcolor></fill> </rect> </group> </definition> </library> <graphic> <bluerect width="100" height="200"> <bluerect> </bluerect></bluerect></graphic> <private> <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 <!-- Regular comment - no asdoc --> These comments will be ignored while scanning the mxml files. <mx:vbox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo"> <mx:button id="myButton" label="This button has comment"> </mx:button></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 a href="Bindable">Bindable, [Exclude](Exclude). There may be others, but during prototyping I found the following to work out of the box [ExcludeClass](ExcludeClass), [Deprecated](Deprecated), [DefaultProperty](DefaultProperty), [Effect](Effect), [Event](Event), [Style](Style) Support for new metadata [SkinState](SkinState) introduced in gumbo will be treated as B feature. Since [Bindable](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 <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. <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:button></mx:vbox> Following is the example for a mxml component which is deprecated. This should result in the "Deprecated NewComp" in the class header. <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:button></mx:vbox> Following is the example for a mxml component which is excluded. This should result in the class getting excluded from the documentation. <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:button></mx:vbox> #### Inline mxml components Any inline mxml components must have the id property in order to the comment to be processed. <mx:vbox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo"> <mx:button label="This button has comment"> </mx:button></mx:vbox> Any inline mxml components has an id property but no comment. It should still appear in the class documentation. <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:button></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. <!--- comment --> ### 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. ## Globalization ---- No globalization issues are anticipated for this feature. ## Localization ---- ### Compiler Features This feature is not expected to introduce any compiler localization changes. ### Framework Features This feature is not expected to introduce any framework localization changes. ## Issues and Recommendations ---- None at this time. ## Documentation ---- Once this specification is signed off, significant documentation will be required to capture the changes and explain the usage scenarios. ----