Why won't my ASdocs Copy?
This post comes from the monthly Flextras newsletter. While we were finishing up the Flextras Calendar, we wrote over 27 pages of ASDocs. I was presented with an interesting issue with ASDocs.
What are ASDocs?
ASDocs, if you're unaware, are special blocks of code you write in your Flex files that can be run through a command line utility to generate an API Reference. The API References you use for the Flex Framework are generated by the ASDocs tool, for example.
ASdocs look like this one, from the changeMonth method of the Flextras Calendar:
* A method to change the month based on the specified increment.
* You can use a negative value to go back in time or a positive value
* to go forward.
* Only has an effect if in the MONTH_VIEW state.
*
* @param value The increment value used to change the month; the
* default is 1.
*
* @see #MONTH_VIEW
*/
The ASDoc are placed before elements in your files, such as properties or method and when you run the ASDoc tool it picks up the text and adds it to the generated ASDocs files.
In the ASDocs segment above you see two ASDoc tags, @param and @see. These tags give special instructions to ASDocs. The @see tags add links to other elements of the API, other classes, or even URL links. The @param tag defines the parameter to a method, and they are given a special place in the ASDoc output.
The @copy tag?
Our Calendar supports most elements of the List class API and the DateChooser API. The Calendar extends ListBase, so most of the properties are inherited. The DateChooser properties, such as firstDayOfWeek, monthNames, or dayNames are implemented as if they were brand new.
We thought instead of writing new documentation for these properties, we could use another ASDoc tag--@copy--to just copy the documentation from the DateChooser class into the Calendar class. The code looked like this:
* @copy mx.controls.DateChooser#firstDayOfWeek
*/
This seemed logical to us, but for some reason the ASdocs wouldn't copy; and the documentation in our generated file was blank for those copied properties. What was the problem?
It turns out that the DateChooser is never used anywhere in our Calendar. As such, the Flex Compiler will automatically optimize the class right out of the SWC file. This is good because it keeps file size low and you do not have to distribute unnecessary classes. Unfortunately, it seems to the ASDoc appears to use the same approach. DateChooser wasn't in the API, so therefore the ASDoc utility couldn't find the DateChooser code in order to copy the appropriate ASDocs from one place to another.
The Solution Part 1!
One solution, and I hated doing this, was to create a dummy variable of the DateChooser type:
Then all was well and the properties would get documented as expected. I don't like this because it artificially inflates the size of the SWC. Thankfully there is a better solution.
The Solution Part 2!
The ASDoc command line tool supports many of the same command line arguments that the Flex compiler supports. We can use the include-libraries argument and point it at the framework SWC. This will make all classes in the framework available to the ASDoc compiler whether or not they are used.
For practical purposes, you want limit your use of this argument when creating swfs for wide release. But, none of that matters when generating ASDocs.
Conclusion!
Did I mention that the Flextras Calendar is out? It supports Flex 3 and Flex 4 and you can download a free developer edition to test it out.
