ASDoc Improvements That I'd Like to See

In a previous blog entry, I likened ASDoc to Javadoc because of the many obvious similarities between them. In this blog entry, I plan to outline a few things I'd like to see included with future versions of ASDoc.

1. ASDoc document MXML XML code.

While I list more than one thing I would like to see improved with ASDoc, none of the others approach this one in terms of how nice it would be to have them added as features. The one thing I'd like to see for ASDoc more than anything else is to see it support my MXML code that is in XML format rather than only covering ActionScript code. One might say that it should then be called MXMLDoc or FlexDoc, but it would be nice to have something that generates documentation for both the MXML and the ActionScript that makes up my Flex applications. It seems that XQuery or XSLT could be used to construct documentation for the XML portions of the MXML code. This is one area where Javadoc doesn't do much better. For example, Javadoc doesn't give us a nice way of documenting our JavaServer Pages (JSPs), though I have postulated the idea of using XSLT to generate such documentation.

I believe that Flex defect SDK-1012 may cover this issue. Defect SDF-85 also seems somewhat related.

2. Allow ASDoc-generated documentation to link to source code.

A relatively recently added Javadoc feature that is very nice is the -linksource option that allows one to link Javadoc-generated documentation with the underlying Java code. I would like to see a similar capability in ASDoc.

3. Allow documentation of private methods and members.

I understand that the usual use of ASDoc-generated documentation is for other users who do not need to know the internal workings of a class and so do not need private members and methods documented. That being said, however, there are situations in which it would be nice to have even private methods and members documented. For example, among development teams, it can be useful to have generated documentation even for the private methods and members. The counter argument to this is that internal teams should have access to an even more authoritative source -- the code itself. However, why not give the developer the flexibility to generate documentation even with private members and methods? This "intermediate" level of documentation can be useful for team leads, project managers, and perhaps even clients who do not want to wade through code, but do want a feel for the design of the system. I like the way Javadoc handles this. It makes the default to not display private member and method information, but this can be overridden with the Javadoc -private option.

4. Have several Flex-related ASDoc defects addressed.

Although relatively minor (and there are work-arounds), I'd like to see SDK-782 fixed so that external ActionScript included code could more easily have its documentation generated with the main MXML file. Other ASDoc-related enhancements that have been captured and look interesting include SDK-12405 ("hypertext links in asdoc descriptions") and SDK-9751 ("Support class level comments in MXML").