Seb Lee-Delisle

Menu

How to set up ASDoc in Flex Builder

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!

This entry was posted in Actionscript, Flash. Bookmark the permalink.

44 Responses to How to set up ASDoc in Flex Builder

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Current ye@r *