Using ASDoc with Bindable metatag and mxml

Question

I am creating the documentation of my flex project using ASDoc and having some issues with the bindable metatag.

• ASDoc doesn't document public Bindable values unless the Bindable tag has an event name associated with it.

For example:

//This is documented correctly
[Bindable("someEvent")]
/*
* public bindable with event name
* */
public var test1:String;

//This is not documented at all
[Bindable]
/*
* public bindable without event name
* */
public var test2:String;

• ASDoc prepends random strings to the names of protected Bindable values if the bindable tag doesn't have an event name associated with it.

For example:

//This is documented correctly as test3  
[Bindable("someEvent")]  
/*  
* protected bindable with event name  
* */  
protected var test3:String;  

//But this is documented as _110251490test4  
[Bindable]  

/*  
* protected bindable without event name  
* */  
protected var test4:String;

To sum it up, ASDoc is not happy with Bindable tags without an event name. The easy solution, it seems, would be to specify an event name whenever you declare something as Bindable. But flex docs say that if u specify an event name with the Bindable tag, then "you are responsible for generating and dispatching the event". My project is almost complete and I've relied on binding (without event names) in a lot of places, making it impractical to go back and change everything - its gonna need a lot of effort; plus the idea of messing up the working code for creating documentation sounds scary to me.

Replacing all [Bindable] instances with [Bindable("blah")] before generating asdoc and then changing them back is the only workaround i can think of. But I feel that there should be a better way.

Adobe bug tracker claims that the problem with public variables have been fixed in the latest build, so I downloaded the latest flex sdk (3.4) and tried with the ASDoc that came with it - but it gave me the same result.

Can anyone shed some light on this issue?

Also, Adobe blog says ASDoc now supports mxml too, but when i tried with the latest (flex 3.4) ASDoc, my mxml asdoc comments (embedded in ) didn't appear in the html page that was generated. does anyone know if latest asdoc is available to download separately?

Answer 1

You don't provide any Jira numbers to check, but...

The ASDoc changes for MXML are only in Flex 4 (IIRC), I'd check the binding bug isn't the same.

Answer 2

While I can't help you with a workaround, the problem is that [Bindable] (no event name) generates wrapper code (I believe a separate property) around the property. This code is obviously messing with asdoc.