howto document your code with ASDoc

Posted At : August 23, 2007 10:52 AM | Posted By : Mark Lynch
Related Categories: Linux, Java, HOWTO, Flex, Windows
Last night I was trying to document our AS3 code, using ASDoc, for a project that we have been working on. For those of you who don't know, ASDoc is a command line utility which allows you to generate code documentation in HTML format. A good example of what ASDoc output looks like would be, Flex 2 Language Reference.

Documenting code wasn't as easy as I thought it would be, so I thought I'd share this with you and hopefully it will save someone some time. I use an Intel Mac and this is what you need to do to get your basic code documentation generated successfully:

1. In your terminal window go to your Flex SDK bin directory. Typically this is located under /Applications/Adobe Flex Builder 2/Flex SDK 2/bin

2. From "bin" directory run this command:

./asdoc -doc-sources=/Users/marko/Documents/workspace/yourFlexProject/ -source-path=/Users/marko/Documents/workspace/yourFlexProject/

If you have any external Libraries in your Flex project you will need to include them in your command:

-external-library-path=/path_to_your_swc/myLib.swc

The key thing to remember for Mac users is that you need to run the command from Flex SDK bin directory and use -source-path option to tell the compiler where the source is located. -doc-sources will tell the compiler to generate output for the current directory and all subdirectories recursively. If you run this utility from any other directory other than "bin", you will get NoClassDefFoundError.

I haven't tried running ASDoc in Windows yet, but it should be very similar to running it on a Mac. And since ASDoc is a command line java utility, you would think it would run on Linux too. Well, for all you Linux users out there, this is the message I got from the compiler:

Error: Could not create toplevel.xml: Unknown OS for ASDoc. ASDoc will only run on Windows and Mac OS X.
That last sentence is pretty self explanatory :)

ASDoc is nicely documented here.

Cheers
Marko

Comments (8) | del.icio.us | Linking Blogs
Comments
[Add Comment]
ALBERT's Gravatar well ,I think since there is the flex builder and It's better for you to insert this into the flexbuilder core ,or provide them as plugin to the flexbuilder platform

although commandline isn't so hard,but it's great job to maitain a user interaction friendly
# Posted By ALBERT | 8/24/07 12:00 AM
Theo's Gravatar ASDoc doesn't seem to work very well on the Mac, I've never been able to make it run properly and all I find is other people having other problems.

For me the problem is that asdoc can't find a file called "overviews.xml". I think it's a file generated by asdoc but that it gets the path wrong somewhere. It's looking for it in $FLEX_HOME/asdoc/xml which doesn't seem right, so I think it mixes it up when something expects a relative path and asdoc is started from the "wrong" directory (which seems like the only way to start it at all on the Mac). Have you encountered this?
# Posted By Theo | 8/24/07 12:09 AM
Marko's Gravatar @Theo
No, I haven't encountered that problem. Did you run asdoc from the SDK Bin directory? You might also try and set $FLEX_HOME to point to "/Application/Adobe Flex Builder 2/ Flex SDK 2". To do this, you need to modify /etc/profile file. In the line under "export PATH", type this in:
export FLEX_HOME="/Applications/Adobe Flex Builder 2/Flex SDK 2"
I didn't have to do this, but it could work for you. Just out of curiosity, are you using Intel or PPC Mac? Let me know how you go.

@Albert
Good point. I guess you could run asdoc inside Flex Builder if you so wish. It will probably take you just as long to get it to work though. For those of you who want to try that option, you'll need to download Eclipse Java Development Tools plugin.
# Posted By Marko | 8/24/07 1:01 AM
Theo's Gravatar Yeah, I've tested all sorts of variants, running it from $FLEX_HOME/bin, $FLEX_HOME/asdoc, etc. I've been modding the shell script, even looked at the XSL to see if I can find any obvious problems.

The only thing I haven't tested, which only occured to me now, is that I may have another version of Xalan (the XSLT processor that I assume runs the show) than asdoc has been tested with. All java tools seem to need their particular version of that package, so it might be that I have something installed which comes before Flex's xalan.jar in the classpath. I'll have to check that out.
# Posted By Theo | 8/24/07 4:26 AM
Marko's Gravatar Good idea Theo. Please let me know if you manage to get to the bottom of it. Good luck.
# Posted By Marko | 8/24/07 9:16 AM
Ruben Swieringa's Gravatar I have not come across an ASDoc-plugin for flex yet, but ANT seems to me like a good alternative, at the least it's less robust then actually having to fill in the commandlines each time you want to generate your documentation.

I wrote a post on using ASDoc with ANT here:
http://www.rubenswieringa.com/blog/ant-and-asdoc
# Posted By Ruben Swieringa | 8/25/07 6:53 PM
Marko's Gravatar Thanks for the info Ruben.
# Posted By Marko | 8/26/07 12:21 AM
Ruben Swieringa's Gravatar No problem marko :)
# Posted By Ruben Swieringa | 11/24/07 12:43 AM
[Add Comment]
BlogCFC was created by Raymond Camden. This blog is running version 5.1.004.