I'm a big fan of ASDoc! I use it to document all of my major library releases (ex. GTween, SPL, Wander, etc).
ASDoc allows you to write simple comments in your AS3 classes, then generate HTML documentation from them. This is great in that it allows developers to maintain source code and documentation simultaneously, and it reduces the overall burden in writing documentation by reading the core API information from the code directly. Unfortunately, the ASDoc tool is command line based, and can be a bit of a pain to work with. There are ant integration tools available, but they don't suit every need or scenario.
That's where ASDocr comes in. Building on the new nativeProcess APIs in AIR 2.0, it provides a simple graphical interface to ASDoc. It walks you through all of the common params ASDoc supports, with help for each of them. You can save configurations for multiple projects, and clone configurations to act as a starting point for new projects.
It only takes a couple of minutes to set up a basic configuration (only 2 settings required) and start generating documentation. ASDocr will display the output from the ASDoc executable, and notify you if an error occurs. You can even use CMD/CTRL-ENTER as a shortcut to run (muscle memory FTW!).
Here are a couple of screen shots showing it in action:
ASDocr is completely free - we built it as an internal tool, then decided to polish it up and give it away to help encourage the use of ASDoc in the ActionScript / Flash community. It also serves as a simple example of what is possible with AIR 2.0.
You can download it here:
You'll need the latest public beta of AIR 2.0 to install it.
It works best with ASDoc v4, which is available with the latest Flex SDK or Flash Builder beta. You can get information on creating ASDoc comments here. We'll probably incorporate a help tab in a future version with an ASDoc tag/comment reference, so everything is in one place.
We'd love to hear any feedback you have on the app. Let us know if you have ideas to improve ASDocr, or if you've found it useful (it motivates us to keep improving it, and releasing new tools for the community).
UPDATE: The latest version of ASDocr, with support for the AIR 2 Release Candidate can be downloaded here.
Comments (53)
I'd really appreciate some Linux love :) Does the beta allow publishing Linux AIR 2.0 apps?
Posted by: TK at January 19, 2010 12:17 PMURL: http://blog.tkassembled.com/
I was actually just wondering about that. I don't think it does, but I'm curious if there are plans to support it.
Posted by: Grant Skinner at January 19, 2010 12:21 PMURL: http://gskinner.com/blog/
This is excellent, Grant! Yes, the AIR 2 beta allows you to use the native process API and creative native installers for Linux as well. In order to create the installers, you will need to do this from a Linux machine. - Rob Christensen, Product Manager, Adobe AIR
Posted by: Rob Christensen at January 19, 2010 12:27 PMURL: http://blogs.adobe.com/air/
Is there ANY way in AsDoc to generate documentation for private members? This is something that still bothers me.
Some docs are for internal use and having the private members listed too would be a huge benefit.
Posted by: Armand at January 19, 2010 12:52 PMURL: http://www.richnetapps.com
Rob - Thanks for the info. We'll try to build a Linux version in the next week or so.
Armand - iirc ASDoc will doc private members unless you give them an @private tag. I agree that it would be very nice if you could specify access level for documentation (public, protected, private) so you could easily build out public API documentation, and internal API documentation.
Posted by: Grant Skinner at January 19, 2010 01:11 PMURL: http://gskinner.com/blog/
Nice work. I would like to see a tool like this add comment editing within the tool, especially where it adds html lists, tables and that you often find in Adobe's language docs. It might be more work than it's worth, but it's one of those things that "if I had time..."
Posted by: Tyler Wright at January 19, 2010 02:07 PMURL: http://www.xtyler.com
Awesome~!
I'll introduce this to my korean friends through my blog.
Thanks for a good thing.
Posted by: Wooyaggo at January 19, 2010 04:00 PMURL: http://as3.kr
"This application requires an update to Adobe AIR that is not available for your system."
The machine has XP SP3, Intel Core 2 Duo, 4GB RAM. Lots of other AIR apps are installed. What could this be complaining about?
Posted by: Mike Slinn at January 19, 2010 04:21 PMURL: http://mslinn.com
Mike, You'll need the public beta of AIR 2.0
Posted by: Ryan Matsikas at January 19, 2010 04:22 PMhttp://labs.adobe.com/downloads/air2.html
URL: http://gskinner.com
Great! thanks a lot for sharing this with us :)
Posted by: Ramiro Araujo at January 19, 2010 07:06 PMURL:
Gosh, this is really, really convenient! And the interface design is simple, clean, and elegant. I like it very much :)
Posted by: Allen Chou at January 19, 2010 08:25 PMURL: http://cjcat.blogspot.com
Always wanted ASDoc to have a front end. Nice work and thanks for sharing!
Posted by: Justin Putney at January 19, 2010 10:40 PMURL: http://ajarproductions.com
This looks really better than the command line app although I haven't been able to make it work. I continously get the 1046 error with some (not all) my external libraries. I am using FDT The linked libraries that break include SWFAddressEvent (not SWFAddress dunno why). Any ideas?
This is the output:
/Applications/Adobe Flex SDK 4/bin/asdoc -source-path "/Users/mga/Documents/FDT Workspace/vgline/src" -output "/Users/mga/Documents/FDT Workspace/vgline/doc" -doc-sources "/Users/mga/Documents/FDT Workspace/vgline/src" -lenient
And one error is:
/Users/mga/Documents/FDT Workspace/vgline/src/com/pingpongestudio/timeline/Timeline.as(1569): col: 39 Error: Type was not found or was not a compile-time constant: SWFAddressEvent.
private function handleSWFAddress(e:SWFAddressEvent):void {
Posted by: mga at January 19, 2010 11:52 PMURL: http://www.mauriciogiraldo.com/blog
I get this error (I only unzipped the Flex SDK):
Load config file C:\Program Files (x86)\Flex SDK\frameworks\flex-config.xml
[Fatal Error] toplevel.xml:3:115: Element type "classRec" must be followed by either attribute specifications, ">" or "/>".
Fout: Can't create toplevel.xml: Element type "classRec" must be followed by either attribute specifications, ">" or "/>".
What do I do wrong?
Posted by: San at January 20, 2010 02:56 AMURL:
DUDE you are amazing!
Posted by: P48l0 at January 20, 2010 05:38 AMURL: http://tracehello.wordpress.com
amazing! thanks a lot!!
Posted by: sitron at January 20, 2010 06:48 AMURL:
Hi Grant,
Thanks a lot for this very usefull tool.
The exclude-classes seems not working. I can't add several lines. When pressing Enter (line break, I'm on PC), the cursor's goes back to position 0 on the first line. Anyway, if I add only one class, it's still parsed.
Posted by: Flo at January 20, 2010 09:56 AMURL: http://13flo.com
Hi Grant,
Unfortunately the installer does not seem to be compatible wit the latest AIR 2 build (prerelease) of the 15th of the 1st - It gives the
'This application requires an update to Adobe AIR that is not available for your system.'
Error, even thought the version of Air I have installed is newer than the one required :-(
Posted by: Conrad Winchester at January 20, 2010 03:37 PMURL:
Hi Grant,
just found your tool, it's really useful. Thank you! It would be awesome, if you would enable the exclusion of complete packages.
I have a package which contains all automatically generated value objects from Flash Builder. There seems to be a problem with them so that asdoc can't handle this files. So it would be cool if I could exclude the whole package.
Posted by: Thomas at January 21, 2010 05:08 AMURL: http://fivedigital.net
wow as always I am impressed with your work
Posted by: sharedtut at January 21, 2010 11:31 AMURL: http://sharedtut.com
Thanx Grant! It's a dream!!!
It works very well with SDK 3.2.
I only have some problems to document class level comments for mxml components. Obviously I have used the right sintax (
Posted by: Fabio Biondi at January 21, 2010 05:26 PMURL: http://www.fabiobiondi.com/blog
x Flo: you are right, there is a little bug in the EXCLUSIONS section but you can exclude all the classes you need using the ADDITIONAL PARAMETER (in the options step):
-exclude-classes "com.domain.className"
Posted by: Fabio Biondi at January 22, 2010 08:20 PMURL: http://www.fabiobiondi.com/blog
wonderful !!!!!!!!!
Posted by: andré felipe at January 23, 2010 12:43 AMURL: http://www.andrefelipe.com/
Amazing, very useful!
Posted by: Pascal at January 23, 2010 03:15 AMURL: http://www.trinidev.fr
Awesome tool!
Posted by: Mitchell Thomas at February 2, 2010 11:42 AMWill not install with the latest version of AIR 2.0 runtime. Fortunately I had the air2_b2_runtime_win_111709 version, which worked great.
URL: http://www.electricbluemonkey.com
Adobe just released AIR 2 Beta 2 today, and this does not install.
Posted by: David Pett at February 2, 2010 04:44 PMURL:
We should be releasing a new version tomorrow for AIR 2 beta 2.
Posted by: Grant Skinner at February 2, 2010 05:01 PMURL: http://gskinner.com/blog/
Awesome, I was just looking into creating docs at the command line and saw this tool, thought it sounded easier.
thanks
Posted by: David Pett at February 3, 2010 04:17 PMURL: http://davidpett.com
This application requires an update to Adobe AIR that is not available for your system.
When version for AIR 2 beta 2 comes out?
Posted by: laakkti at February 4, 2010 02:49 PMURL:
Doesn't work for me.
Posted by: Jloa at February 5, 2010 09:35 AMI've already have the beta2 air installed.
However, it doesn't get installed; dies with an exception "This app needs an updated version of Adobe AIR... etc"
URL: http://chargedweb.com/swfsize/
How can I exclude multiple classes with the additional params? I tried it like this:
-exclude-classes "com.myapp.services.*;com.myapp.vo.*"
But it doesn't work...
Posted by: Thomas at February 8, 2010 09:26 AMURL: http://fivedigital.net
Is it possible to add external libraries *with source code* (not swc)? About each and every of my projects use library code like that (in different directories, updated via svn).
Couldn't find that functionality neither in the confusing asdoc documentation nor in your (great) tool.
Any idea? Or is this just not possible?
Posted by: Severin Klaus at February 16, 2010 06:39 PMURL: http://blog.betabong.com
Love the tool and it seems to work great, but I keep getting error when I generate the docs:
[Deprecated] Xalan: org.apache.xalan.res.XSLTErrorResources_en_US
I'm sure it has something to with ASDocs and not necessary ASDocr, but does anyone have any idea what causes this?
Posted by: Michael at February 17, 2010 12:36 PMURL:
Hi, does anybody have a link to the air version which works with ASDocr? I'm not able to run it because I get "This app needs an updated version of Adobe AIR...".
thanks
Posted by: solano at February 19, 2010 09:06 AMURL:
Yarp - buggered. don't install. Uber shame - looks like a tool which the world needs! Nice one Grant.
Posted by: Jay Jagpal at February 22, 2010 05:37 AMURL: http://strangemother.com
the update has been posted here:
Posted by: David Pett at February 22, 2010 06:07 PMhttp://www.gskinner.com/blog/archives/2010/02/asdocr_update_f.html
URL: http://davidpett.com
Thank you very much!
Posted by: solano at February 23, 2010 04:55 AMURL:
It seems like it breaks with any class that either -implements an interface- or -extends a class-
For example:
public class PopulateStates extends DataProvider
ERROR: "The definition of base class DataProvider was not found."
What am I missing? I am not trying to document DataProvider. So it isn't really all that necessary to have it try to find it right? I tried "lenient"...that didn't seem to work. Please advise.
Posted by: Nail at March 16, 2010 09:21 PMURL:
I am using asdoc for an actionsciptfile which is a collection of utility finction- is not a class or part of an interface/namespace----how do I generate documentation ina sdoc for such a file?
Posted by: mk at March 18, 2010 11:01 AMURL:
@San - you have "@" sign in your comments (@classRec) and it breaks down the asdoc. I had it in xml property example i my ascomment. Removed and its ok.
Posted by: webheart at March 27, 2010 07:50 AMURL: http://webheart.pl
BUG
I have AIR version 2.0.0.11670 on Mac OSX 10.6. However, I cannot install the app due to it telling me that I don't have AIR version 2.0. It lies. :)
Help please - this looks awesome
Posted by: John Bailey at March 29, 2010 08:42 AMURL: http://flashmoments.novelastudios.com
Please help...need advice on how to use this awesome utility with class files that either -implements an interface- or -extends a class-
For example:
public class PopulateStates extends DataProvider
ERROR: "The definition of base class DataProvider was not found."
What am I missing? I am not trying to document DataProvider. So it isn't really all that necessary to have it try to find it right? I tried "lenient"...that didn't seem to work. Please advise.
Thanks in advance!
Posted by: Nail at March 29, 2010 12:06 PMURL:
Hi Grant. Forgive my strange question but... I am experiencing a problem with installation.
Posted by: Sacha at April 18, 2010 06:31 AMYour app installer says i am missing an update for air that I my system does not support. I do have a MacBook Pro 17" with snow leopard 10.6.3 and i just updated Air with your link at the Adobe labs. I rebooted, unistalled and reinstalled air, but your installer keepssaying i am missing something about the air enivronment. Since I can't wait to use your ASDocr, could you please give me a hint? Thanks a lot, in advance, for your time. s@ch@x.
URL:
Is there any way to get this to work on OS 10.4? I'd really like to use this but I can't install it. I'm guessing it wants OS 10.5.
Posted by: Mitchell at May 6, 2010 04:40 PMURL: http://webdevils.com
I'm trying to install the ASDocr with the RC of AIR 2 runtime and the install keeps failing. Could please update ASDocr to install with the RC of AIR 2. Thanks.
Posted by: Sofiane at June 2, 2010 11:11 AMURL:
Grant please help us installing asdocr on mac. I keep getting the same message also after upgrading the new beta (may 2010)... I really don't know how to solve it. It says my version is not working… a I am sure I do have the latest beta isntalled from the labs…
Posted by: sachax at June 4, 2010 08:31 AMThank you for your time (and for asdocr, if I am able to install it :( ).
URL:
Hi guys, in order to install ASDocr using the latest AIR Runtime, you will need to install version 1.2.
Posted by: Shawn at June 4, 2010 10:06 AMInstructions/links here:
http://www.gskinner.com/blog/archives/2010/05/asdocr_update_f_1.html
URL: http://gskinner.com
An error message pop up for me when I try to install it:
Error
The application was unable to install because it was snt configured in a right way. Contact the author to obtain assistance.
Posted by: Daniel Dourado at June 11, 2010 03:04 PMURL:
Nice looking tool:) as I can't tell anything more becuase I am stopped by following error:
Loading configuration file C:\flex_sdk_4\frameworks\flex-config.xml
[Fatal Error] toplevel.xml:2375:4: Element type "id" must be followed by either attribute specifications, ">" or "/>".
Error: Could not create toplevel.xml: Element type "id" must be followed by either attribute specifications, ">" or "/>".
is it something I am doing? Or my classes, or buggy asdoc?
Posted by: Lukasz 'Severiaan' Grela at June 22, 2010 08:36 AMURL: http://greladesign.com
I'm also getting the [Fatal Error] toplevel.xml Error.
Posted by: J T at June 28, 2010 10:22 AMURL: http://google.com
The toplevel.xml error is an internal error, thrown by the asdoc binary, when it has problems parsing your asdoc comments. It's something that is outside the control of ASDocr.
Generally we've seen it occur due to special characters within your comments/code, or due to some error in commenting syntax, ie "@privatecomment" would throw this error, due to the missing space after "@private".
Best tips to isolate this:
Posted by: Shawn at July 2, 2010 09:25 AM1. Turn on exclude-dependencies
2. Use doc-classes to document single classes, until you find the one that is causing the error.
3. Once you find the problem file, you need to parse through it to try and find the offending line(s).
4. Comment, fix, or delete those lines, and run ASDocr again.
URL:
This sounds as a good idea to at least pinpoint the problem, but surely it is a BUG of the ASDoc (without r:) as on error in comment it should have an option to skip it.
Posted by: Lukasz 'Severiaan' Grela at July 7, 2010 04:50 AMURL: http://greladesign.com
I'm having a hard time generating a swc for a code library with asdoc using SDK 3.5.
not necessarily using asdocr, I use the asdoc tool directly.
Have anyone any ideas on that?
Posted by: Atar at July 12, 2010 06:31 AMURL: http://dhost.info/atarsh