ASDocs External Tool in Flex or the Flex Plugin for Eclipse

All right so at work, ickydime has built a nice library of classes, which hopefully I will be able to add to soon, that we use all the time. It is getting to the point that we needed to start commenting the classes and have some documentation for each class so we didn’t need to explain it all the time. That is where I came in.

I have ran the ASDocs tool before but only on one folder and now I needed to run it against an entire library of folders and classes as well as adding library paths. I found a lot of information out there about running the ASDoc tool but usually it was doing it on one folder and that is it. So I spent about 10 hours trying to get this to work and I finally figured it out.

I’m posting my code and some screen shots so I hope this helps.

First if you don’t know where this tool is at it is located in Flex, or in my case Eclipse with the Flex plugin, on the top tool bar. It looks like a play arrow with a tool box under it.

Make sure you have the folder selected in your Project menu on the left side of the screen when you start this process. This is not a requirement but it will make sure you run the tool on the right folder. Now that you know where the tool is click the black arrow on the right side of the button and a drop down will pull up.

When the drop down comes out you will want to click on the “External Tools Configurations” button. Once you click on this it will launch a new window that looks like this.

Now it is time to fill it out so you can run the script. On the left hand side of the window click on “Program” and then click on the paper with the “+” sign on it.

Once you do that a new configuration task will be added to your toolbox. Now you will fill it out. In the middle of the window the first thing you see is Name: This is where you will put the name of the tool you want to run. I used the name of our library and then put ASDocs after it. You don’t have to do this but it will be helpful if you have a lot of libraries and then you can just pick the one you want to run and run it.

You WILL NOT BE CHANGING TABS so make sure you leave it on the Main tab. The next thing you want to fill out is the Location of the asdoc.exe(pc) or asdoc(mac). Mine was located here “C:\Program Files (x86)\Adobe\Flex Builder 3 Plug-in\sdks\3.2.0\bin\asdoc.exe” but that is on a PC. It should be the same on a Mac because they are both within the Flex folder structure.

The next line you will fill out is the “Working Directory”. This is the project that you are going to be running the tool on. You can search for it in the File structure or the workspace. I found it easier using the workspace. If you use the Browse Workspace to find your project it will look something like this, ${workspace_loc:/basement_core/classes/basement_core}. Just make sure you have the top folder listed here so you will get all your folders and classes. If you go down to far you will miss some folders and classes. The image below should show you what you should have at this point

The top part is easy and now comes the good stuff. The big text box at the bottom is where all your arguments come into play.

As you can see there are a few arguments that we need to put in to get all the classes covered.
Here is the enitre code:

-doc-sources .
-doc-namespaces
-library-path "C:\Program Files (x86)\Adobe\Adobe Flash CS4\Common\Configuration\Components\Video"
-library-path "C:\Workspace\AS3 Workspace\SoundSync\bin"
-library-path "C:\Workspace\AS3 Workspace\GreenSock\bin"
-library-path "C:\Workspace\AS3 Workspace\Tweener\bin"
-output docs
-main-title "Basement Core Documentation"
-window-title "Basement Core Documentation"
-footer "2009 Copyright of The Basement Design + Motion"

I will start will line one and go through each one.

-doc-sources . (You have to make sure the period is at the end with a space after the sources. This is the statement that tells the compiler where all your classes are located. Since you already had the folder selected above basically we are just saying get all the classes. The period is like a wild card and tells the compiler to search in all folders.)

-doc-namespaces (This will handle all the classes that refer to other classes inside the folder structure. This is the one that had me stump for so long)

-library-path "C:\Program Files (x86)\Adobe\Adobe Flash CS4\Common\Configuration\Components\Video" (this is a library path of outside classes and swc. If you open up the .actionScriptProperties in your project you will see all of the library paths, that is if you have them. This path was bringing in the FLVPlaybackAS3.swc. I was getting an error here because the AS2 playback was in there as well. I removed the AS2 version and it worked fine. Of course you could have excluded the swc but that is whole other can of worms. You do have to include the “” around the path like it is shown)

-library-path "C:\Workspace\AS3 Workspace\SoundSync\bin" (here is another library path that goes to the SoundSync.swc)

There are two other classes that I included I’m going to skip them for time sake but make sure you put all your library paths in there or you will get an error.

-output docs (This line is going to create a folder named docs in the same folder that your running your external tool on. It will produce all the HTML files that are needed for you docs.)

These last three are optional but they will personalize your ASDocs a little more.

-main-title "Basement Core Documentation" (This will create a Header basically for your docs and you have to put the “” around the title)

-window-title "Basement Core Documentation" (This line will put whatever is in the “” into the title bar of the web browser)

-footer "2009 Copyright of The Basement Design + Motion" (Here is the last line and this will put a footer at the bottom of your doc files)

After all of the code is entered press the Apply button and then the run button and wait. It usually takes a couple of minutes to finish.

I hope this tutorial helped and saved you some time.