ASDoc'ing MXML Components
I want to say a special thank you to my wonderful friend Joan Lafferty at Adobe for helping me and my constant annoyance at the ASDoc builder and MXML components. While I will thank Adobe for waiting just long enough to make this change that I was forced to learn to do everything in Actionscript, it is a nuisance when working with teams of varying skills to try and create ASDocs. The biggest problem is in the past when the build scripts would reach a MXML component the dependencies wouldn’t be found and the builder would fail. Apparently someone at Adobe noticed this and after skipping many SDK updates to update the ASDoc tool, now some development has taken place and you can ASDoc MXML Components.
The following information is a summary of the changes to the MXML ASDoc tool. Attached is also the PDF document that discusses each of these points in detail.
Documenting MXML Elements
MXML Documentation is now possible within MXML component’s through the asdoc element tag, notice the 3 dashes at the beginning:
With this you can add class level, and children level comments within mxml.
Example (from the Adobe docs):
<!-- asdoc\MyVBox.mxml (standard xml comment) -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
-->
<vbox xmlns="http://ns.adobe.com/mxml/2009">
<!---
Comment for button
-->
<button id="myButton" label="This button has a comment"/>
</vbox>
What is really nice is these comment blocks ignore the //*, *, and **/ characters! So copying and pasting from Actionscript file ASDoc sections will not break your documentation.
Documenting Actionscipt in the MXML Script Block
Actionscript within the script block follows the same rules as any other Actionscript ASDoc tags.
Example (from the Adobe docs):
* For a method in an <Script> block,
* same rules as in an AS file.
*
* @param eventObj The event object.
*/
public function handleClickEvent(eventObj:MouseEvent):void {
dispatchEvent(eventObj);
}
Documenting MXML metadata tags
Even Metadata tags have had a look over and can be documented. An example of this is provided.
Example (from the Adobe docs):
<![CDATA[
/**
* Defines the default style of selected text.
*/
[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]
</metadata>
That’s it, nothing huge but HUGELY important.
The full document can be downloaded here.
I can’t get this to work, I don’t see any class level docs.
After receiving this information from the Flex Dev team I was excited to test it. Sadly I too have had issues with class level docs on MXML Components. This have been addressed in Fx4 and the Fx4 AsDocs compiler. Hopefully you can hold out till then
I never knew about this ASDoc style for MXML component till I read your blog. This is cool. Thanks for sharing this information