I’ve basically spent about a day working out how to use ASDoc, and all I can say is, what a nightmare! If I wanted this kind of unintuitive, problem-ridden, poorly-documented ridiculousness I’d be a Linux user! (no offense meant, but you Linux guys seem to thrive on this sort of thing!)
Excluding external libraries
Our project has loads of external classes in libraries (one is papervision, others are various Plug-in Media libs), and I really would rather it didn’t try to document them all in the same documentation. And I couldn’t figure out how to stop ASDocs from trying to compile the classes in these libraries.
And if you don’t include the libraries, ASDoc fails badly! So I could either include them in to the docs (which seemed to break anyway) or just exclude them. But is there a way to exclude them?
It turns out that there is, and that is to list every class that you want to exclude! Er yeah that’s probably about 2,000 classes so not going to happen!
Although there is a handy way to generate this HUGE list of classes using the AIR app Dita. But I think I’ve kinda worked out how to use ASDocs now in a way that stops you needing to do that.
Adding external swcs
The big secret that no one seemed to be telling me! If you add a swc file it no longer fails to find the classes you’re referring to. But most importantly it doesn’t try to write docs for them!
So here’s how we set it up :
Step 1 : Set up an external tool in Flex.
Open Flex Builder (we’re using FB 3). See that little green play button with a suitcase on it? In the top left? Click on the down arrow next to it and then “Open external tools dialog”.
Step 2 :
Click on the “New Launch Configuration” Button. it’s the white sheet of paper with a “+” on it.
Step 3 : Find your asdoc file.
Give it a name. Maybe ASDocs or something equally unimaginative. Then set up the Location field; click on Browse File System and find your ASDoc file in the Flex SDK. For me it was in /Applications/Flex Builder 3/sdks/4.0.0.4021/bin/asdoc. If you’re on a PC you should probably point to asdoc.exe.
Step 4 : Point to the project folder.
In the “Working Directory” field, type ${project_loc} – this will point to the project folder for whichever project you are currently in.
Step 5 : Set up the arguments.
in the arguments field point to your source path with the following two arguments :
-source-path src
-doc-sources src
This assumes that you set up your projects with the default source folder called src. So it’ll look into your project folder’s src to find all the classes to make docs for.
And then add arguments to point to the swcs for your library projects, for us it’s :
-external-library-path=/Users/seb/Documents/FBWorkspace/PluginLibs/bin
-external-library-path=/Users/seb/Documents/FBWorkspace/PluginBrain/bin
-external-library-path=/Users/seb/Documents/FBWorkspace/Papervision3D/bin
Of course this assumes that you use library projects in Flex Builder. I guess this will work as long as you have swcs for your code library. Either way you need to point at it.
I’m sure that this won’t work for all of you but I haven’t seen this approach documented anywhere so I thought it may help. And good luck!
thanks:
http://sebleedelisle.com/2009/03/how-to-set-up-asdoc-in-flex-builder/
