Posted At : August 23, 2007 10:52 AM
16 Comments
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:
If you have any external Libraries in your Flex project you will need to include them in your command:
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:
ASDoc is nicely documented here.
Cheers
Marko
16 Comments
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
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?
@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.
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.
Good idea Theo. Please let me know if you manage to get to the bottom of it. Good luck.
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
Thanks for the info Ruben.
No problem marko :)
So I ran the command, and it seems to have been successful, though its telling me I have many code errors in my AS. However, where should the asdoc have compiled to? Where did the documentation go?
Hi Jack, If there have been errors as opposed to warnings I don't think the documentation will be generated - work through the errors - most likely missing libraries and you should be able to get it playing nice.
Cheers,
Mark
But there's so many!
When I compile my SWF I get no errors, isn't there a way to make the asdoc compiler less-strict?
Hi Jack,
Having not seen the errors, I'd guess they likely stem from a missing library, that flexbuilder is automatically including for you. So it's not a case of telling the asdoc compiler to be less strict, just giving it enough info to compile.
Can you compile the code from the command line using the mxmlc compiler? I'd hazard a guess that if you fix the first error then most of the other ones will disappear at the same time.
Cheers,
Mark
Thanks Mark, I finally got it working.
Turns out there were a few issues:
1. One was that I was using the "automatically declare stage instances" in my AS3 publish options.
I had to disable this and manually declare all stage instances.
2. I also had some linked library items that Flash was also automatically generating classes for. I had to create these classes manually as well.
3. On top of that, I needed to add a class path to an external library I was using (the Flash FocusManager).
Once all those things were out of the way, the documentation generated successfully! Thanks :)
Does anyone know if this works with Flex 3 on a MAC, or if theres anything else out there that does?
JP,
As far as I know there are no differences between Flex 2 and 3 in terms of generating ASDocs. If you follow the steps in this post, you should be able to generate the docs in Flex 3. It worked for me.
Cheers
Marko
Marko,
I believe you are correct, I was able to generate ASDoc using the Flex 3 SDK following the above tutorial.