Face it. Documentation is a total pain. Fortunately, generating it doesn't have to be. And while projects like NaturalDocs make things a little easier (and cleaner) to work with, there's nothing quite like a good ol' Adobe style, frame loving, totally unorganized doc folder.
First things first: you've got to have ASDocs. Unfortunately, to the best of my knowledge, it is no longer available from Adobe as a separate download. Instead, you have to pull it down as part of the larger Flex 3 SDK, which is free.
Seriously, though. Commenting for ASDocs is extremely easy and ultimately a great way to go if there's even the slightest possibility that someone else might look at your code. Plus, it's standard and has a lot of great benefits, like showing up in introspection for those of you developing in FDT 3. And, if you are developing flash/AS3 in Eclipse, it's super easy to set up documentation generation at the click of a button. Screenshots and more after the jump.
First things first: you've got to have ASDocs. Unfortunately, to the best of my knowledge, it is no longer available from Adobe as a separate download. Instead, you have to pull it down as part of the larger Flex 3 SDK, which is free.
Once you've pulled down the SDK, toss it someplace handy (for this example, I've placed the entire folder in my applications directory). If you use any kind of external/linked libraries, you can add those in the flex-config.xml file, found in the frameworks directory.
Now that we have that part set up, its time to configure an External Tool in Eclipse. Go to "Run -> External Tools -> Open External Tools Dialogue". Select "Program" and click on the little document with a plus symbol to create a new one. Enter the following info:
Location:
/Applications/flex_sdk_3/bin/asdoc
Working Directory:
${project_loc}
Arguments
-source-path "${workspace_loc:/${project_path}}/src" -doc-sources . -templates-path "/Applications/flex_sdk_3/asdoc/templates/" -output docs
This will generate documentation based on the project you currently have open and place it in a folder called "docs" within your working directory. Here is a good place to note that you cannot have any spaces anywhere in your project path. Otherwise ASDocs will throw a fit.
Once you've run the tool once, it will appear when you click on the External Tools icon in Eclipse, as seen below:
The final step: actually commenting your code! Thank goodness for us, the syntax for this is mercifully simple. Here's a quick example:
- /**
- * Sets the x value to the value of n.
- * @param n Value that x should be set to.
- */
- public function init( n:Number ) : void {
- x = n;
- }
This is just the start of a beautiful thing. A good primer on commenting your code can be found in the flex documentation.
And there you have it! It's important to remember that this implementation may/can often be buggy and may require you to get into that config file and do some guessing and checking to get things working right for your setup.
There are some other methods out there for Eclipse/ASDocs bliss that use ANT to accomplish the same thing, though I have yet to really dig into any of them. It's also worth noting that a similar setup using NaturalDocs (or indeed any other command line tool) is extremely easy and may work better given your needs.
Leave a comment