Categories
General

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!

44 replies on “How to set up ASDoc in Flex Builder”

This is great, Seb! Out of all the searching I went through when first learning to create asdocs, never once was this method brought up. All I could find were tutorials with using terminal (//livedocs.adobe.com/flex/3/html/help.html?content=asdoc_1.html).

The terminal method is nice, I mean it does the trick. But it was kind of annoying having to save the output to text file, and keep track of that file for future updates/additions. I really like the idea of setting the params up once, save them in Flex, and only pressing a button to make updates. So much easier!

Kind of ironic. Here we have this great tool in asdocs, for keeping our classes documented and consistent, but all the documentation to create them are scattered.

Anyway, thanks for sharing!

Great article Seb! I thought I was the only one who fought with ASDoc in the past. You gave me hope. I’m gonna give it a try tomorrow (again)!

Yea ASDoc can be a real pain. My typical setup is to use an XML config file that explicity list only the classes I want to document. You can load the xml with “-load-config” argument then list the classes individually within the “” tag.

Looks like it stripped out the quoted tag in my comment. The tag I was referring to is the “doc-classes” tag.

-justen

I haven’t tried excluding class files with it, but I use an apache ant script to run asDoc, and I don’t see why that script couldn’t be modified to exclude class files. Most of the time I use the Mac OSX Terminal with the SDK, but the ant script can be linked to FB via the external tools no problem from what I recall (unless I’m recalling Eclipse with the FB plugin). For those curious, I have the ant script at the following post, any edits such as the above that could be added to it I’d love to hear about (to improve it): //blog.anselmbradford.com/2009/01/06/curious-about-adobe-open-source-get-started-with-the-flex-sdk-on-mac-os-x/

Looks like you have other woes than us, but I can easily agree that AsDoc isn’t Adobes finest moment. Maybe version 4?
We use Ant tasks for running asDoc. It doesn’t make the setup much easier, but maintaining and editing is a breeze.

Hi Seb,

nice entry. An additional note:

On Windows systems, if something like “Could not find JVM” comes up, try to set the environment variables for the external tool. To do this follow these steps:

– Edit the external tool again#
– Click on tab “Environment”
– Click New
– Enter “JAVA_HOME” as the name
– Enter your Java directory (JDK or JRE) as the value, this must be the path to the bin directory, with forward slashes (/ instead of – even on Windows). Quote it, if you have a directory with a space in it (e.g. due to “Program Files”.
– The row should look sth. like this:

JAVA_HOME “C:/Program Files/Java/jre1.6.0_06/bin”

Hope this helps,
Cheers Thomas

DUDE YOU ARE MY HERO I’VE BEEN TRYING TO GET THE ENVIROMENT VARIABLE THING FIGUERED OUT FOR DAYS AND YOUR POST SAVED MY ASS!!!
THANK YOU!

And a second side note: If you’d like to create docs for AIR applications/libraries, use aasdoc.bat instead of asdoc.exe. I just stumbled over some errors with Window, NativeDragManager, etc… and realized over the documentation that AIR needs to have some additional parameters.

I believe you can currently list packages with the “*” wildcard to include all classes in that package. For our current ant task we have an exclude-classes param that looks like this

-exclude-classes ‘fl.transitions.*’

to prevent the adobe fl classes from being doc’d. I believe you can specify multiple packages in this format to accomplish what you are describing.

Great post Seb. It’s a bitch to set up and I miss using Ant in FDT. Next I have to look into getting Ant to compile an ActionScript Project and open up Flex Builder’s debugger. Once I get that running I can go back to using Ant for all my builds. Ant was so much better because I could automate it to compile my project, rsync to my server, open the testing url, and do the documentation update in the background. Oh well, one day Adobe will make this a little more user friendly…

Hi Seb,

Nice article. I found one here about Flash and ASDoc,…
code.google.com/p/flashgraph/wiki/ASDocWithFlash

I got it working although I have to remove my SWC once I want to compile my main FLA for some reason.

John McDermott

Oh BTW, I had to change all my “private ” statements to “protected “, to get them to be documented. Unlike JavaDocs there is no -private flag. I think someone has already pointed this out to Adobe Bug tracking, so hopefully they will change this soon.

I don’t suppose you know of a way to get a comment in at the package level?

Ahh, just found the answer to my own question here,…
w w w ericfeminella.com/blog/category/actionscript-30/

…to document packages you need to specify the -package argument to the asdoc compiler.

-package foo “Foo package comment”
-package foo.bar “Foo Bar package comment”

… sorry, for SDK 3.3 actually it should be,…

-packages.package foo “foo package comment”
-packages.package foo.table “foo.table package comment”

I couldn’t get a comment in the All packages window so I edited one of the asdoc template files, to put a link in to my diagram SWF

C:Program FilesAdobeflexSDK_3.3asdoctemplatestitle-bar.html

Hopefully Adobe will think to get this going in Flash and Flex in a MUCH easier way. Hope this has been useful to someone.

Nice aticle. I am having problems getting it working. I get errors that look like compiler errors, but it all compiles correctly outside of ASDoc. For example I get:
/flex/com/ecast/BeltModel.as(189): col: 36 Error: Type was not found or was not a compile-time constant: ConfigurationChangeEvent.

This class is an import. I have tried excluding it individually, or as a whole with wildcards like this:
-exclude-classes “Ecast.*”
but no change.

Any ideas??

Great post, Seb!
But using Flash Builder 4 beta 2, skd 3.4.1 I have this error:

Error: ” is not a directory
Use ‘asdoc -help’ for information about using the command line.

also if I use it as a command line.
Maybe some error in flex-config.xml (I’ve the default)… but I did’nt found it.
Can You please help me?
Thanks

Just a note: all seems to be correct if I use the asdoc command from the sdk 3.3 bin folder instead…
Thanks if someone can help me.
-g

[…] The best way seems to be to exclude all classes from included SWC libraries, as shown in “How to set up ASDoc in Flex Builder“. […]

Thanks for the blog, it really helped. As usual though, things never work straight off, so here’s the problems I had and how I fixed them.

First, I followed these instructions above as Seb describes.
I use many external swc libraries in the ‘libs folder so I added ALL of them.
Then I suppressed the strictness and warnings, and finally the Embed paths to my image assets throughout the source code had to be changed from
source=”@Embed(source=’assets/icon-arrow-down.png’)” to
source=”@Embed(source=’/assets/icon-arrow-down.png’)” so notice the pre-pended slash.

The final arguments block in FlexBuilder external tools looks like this:

-source-path src -doc-sources src
-strict=false
-warnings=false
-external-library-path=libs/AdvancedAutoComplete.swc
-external-library-path=libs/as3corelib.swc
-external-library-path=libs/flexlib.swc
-external-library-path=libs/FlexSpy.swc
-external-library-path=libs/ilog-elixir.swc
-external-library-path=libs/ilog-elixir_rb.swc
-external-library-path=libs/Mate_08_9.swc
-external-library-path=libs/ModuleLoader.swc

Make sure you have the project selected in Flexbuilder before running the asdoc tool (something I tripped up on very easily).

If you are still getting those red errors, just work through them and think about why they could be failing. Good luck.

great article, thanks 🙂
I have a project which uses the swc of a library project in the same workspace, added via “add swc” in the Library path window.
when I try to run the ASDoc tool it insists on trying to create documentation for the lib project as well. I know I can explicitly exclude this library project using -external-library-path, but since I create the external-tool for the whole workspace and would like to use the same one with different projects, I’m trying to find a way to automatically exclude all “referenced libraries”. they are not all necessarily under the same folder, and definitely not under “libs” folder.
any ideas on that?

Hi,

I am using flex 3.5.0. I am following all the instructions specified in this article and comments. But i am still i am getting the same issue like

Loading configuration file C:Program FilesAdobeAdobe Flash Builder 4sdks3.5.0frameworksflex-config.xml
Adobe ASDoc
Version 3.5.0 build 12683
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.

Error: ” is not a directory

Use ‘asdoc -help’ for information about using the command line.

And one more question, I have not only external libraries but also dependent projects also. So i can i specify them.

Can you help…

Thanks,
Ravikumar Maddi

From other posts on this .. one reason is the lack of asdoc/templates folder in the SDK e.g. my FlashBuilder plugin SDK was missing it – need to use an SDK that has one, or transfer one across from a donor SDK

Running into an issue in Flash Builder 4.5

col: 1 Error: The definition of base class Object was not found.

Guessing this is due to me needing to add a flash swc – any ideas?

Hello 🙂

TanQ so much for this nice tutorial.

You mentioned “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.”

So, there is a question here: How can we exactly point to the project libraries here?! Would you mind if I ask you describe the solution here?!

Thanks again 🙂

On windows 7 64 bit I needed to make sure that asdocs was pointing to a 32 bit JRE. In other words I downloaded the 32 bit JRE from Oracle and then edited the file,…

flex_sdk_4.6binjvm.config

and the altered the appropriate line,…
java.home=

to read,…
java.home=C:/Program Files (x86)/Java/jre7

(Note the FORWARD slashes and NO SPACE after the equals)

On the matter of targeting libraries this is what my batch file currently looks like,…

“C:Program FilesAdobeflex_sdk_4.6binasdoc.exe”
-doc-sources ../_commonclasses ./classes
-output asdocs -library-path ./roulette_dev.swc
-library-path ../_commonclasses/as3corelib93/lib/as3corelib.swc
-templates-path asdocs/templates
-metadata.publisher “John McDermott”
-main-title “ActionScript 3.0 client documentation (version 4.1 28/02/2013)”
-window-title “ActionScript 3.0 client documentation (version 4.1 28/02/2013)”
-footer “Copyright © 2011 NetPlay TV”
-strict=false
-external-library-path “C:Program FilesAdobeflex_sdk_4.6frameworkslibsplayer10.3playerglobal.swc”

(Note well using a playerglobal.swc later than 10.3 has JSON inbuilt so it seems conflict with the JSON in as3corelib.swc which I am using)

Comments are closed.