Update: Flex now includes ASDoc. The documentation is here.
ASDoc, the Flex and AS3 documentation tool, is now available on labs:
http://labs.adobe.com/wiki/index.php/ASDoc
The page on labs has everything you'll need to get started: a link to asdoc.zip, instructions on installation, an explanation of the examples, and links to the two additional pages of ASDoc documentation.
If you have any questions on ASDoc, you can ask them here or on flexcoders, and I'll try to answer them.
Comments (41)
I'm just wondering if ASDoc will work with ActionScript 2.0 classes as well?
Posted by Jason | August 14, 2006 5:44 PM
Posted on August 14, 2006 17:44
It's great! By the way, I have a question.
When I set -compiler.actionscript-file-encoding for using japanese charactor set in actionsctipr comment line, it could'nt convert comment into asdoc correctly.
I could not read asdoc which was completely garbled. Any idea?
Posted by sato-shi | August 14, 2006 7:40 PM
Posted on August 14, 2006 19:40
Jason, ASDoc does not work with ActionScript 2.0 classes. It uses the Flex compiler, which only supports ActionScript 3.
sato-shi, I haven't heard of this problem, but I don't think Japanese characters have been tested, so it's probably a bug. If you could send a test case to me, at brian_at_deitte.com, we'll look into this.
Posted by Brian Deitte | August 14, 2006 9:55 PM
Posted on August 14, 2006 21:55
Thank you for replying quickly. I sent you sample code and image. If there are any bugs, of course I can test and check japanese charactors. Thank you!
Posted by sato-shi | August 14, 2006 11:07 PM
Posted on August 14, 2006 23:07
I'm getting the following error while trying to run AS3Doc over a couple of AS classes. "Error: The definition is in circular inheritance." It seems that a custom get/set pair using a custom class and a [Bindable] metadata tag without an event name causes the problem. I have an example handy if more explanation is needed.
Posted by Daniel R. | August 15, 2006 11:57 AM
Posted on August 15, 2006 11:57
Daniel, I saw another meesage about the "circular inheritance" problem, and they solved it by using "include-classes" instead of "include-sources". I'd like an example if you can send me one, so I can fix this for the next release- my email is on the right toolbar.
sato-shi, you mentioned you sent me sample code, but just so you know, I didn't receive anything.
Posted by Brian Deitte | August 15, 2006 2:18 PM
Posted on August 15, 2006 14:18
Oh I'm sorry. My e-mail could'nt send with attached files. I tried to send again without attached files. You can see these files where download site. Thank you.
Posted by sato-shi | August 15, 2006 9:28 PM
Posted on August 15, 2006 21:28
Here's the first non-Adobe ASDoc use I've seen: http://renaun.com/flex2/fms/ConnectionMonitor/docs/
Renaun also added an explanation of how he built this: http://renaun.com/blog/2006/08/24/89/
Posted by Brian Deitte | August 24, 2006 10:44 AM
Posted on August 24, 2006 10:44
I've found the following issues:
1. @throws does not show the error name (at least for toplevel Errors), e.g.
@throws ArgumentError some description
2. @author is ignored, e.g. @author Juergen Failenschmid
It would be great if some way of inline links could be supported, as in Javadoc's @link.
Posted by Jürgen Failenschmid | August 25, 2006 2:42 PM
Posted on August 25, 2006 14:42
Another issue:
@see #someMember
The last character of the referenced member is omitted in the link, thus the link does not work.
Posted by Jürgen Failenschmid | August 25, 2006 3:58 PM
Posted on August 25, 2006 15:58
It turns out that @see #someMember works just fine. I forgot to write
@see someFunction()
to refer to a function rather than a property.
Posted by Jürgen Failenschmid | August 25, 2006 4:11 PM
Posted on August 25, 2006 16:11
Hi Jürgen, thanks for the information. I'll get the @author and @throws bugs into the system and will look into getting them fixed for the next release.
Posted by Brian Deitte | August 26, 2006 2:03 PM
Posted on August 26, 2006 14:03
Hi Brian, thanks for all your effort. Here's another enhancement request: @value (as in Javadoc).
Posted by Jürgen Failenschmid | August 26, 2006 6:57 PM
Posted on August 26, 2006 18:57
It seems that properties marked "internal" show up in the generated docs when using asdoc. Shouldn't this not be the case? It automatically hides classes marked "internal"
Posted by Van Nostrand | September 5, 2006 4:49 PM
Posted on September 5, 2006 16:49
Another question. I'm writing an API -- I have what would normally be an abstract base class. I have marked the class "internal" -- which seems to be the best compromise since API users can't get to it that way. There are two classes that extend this abstract class. I would like to have the methods of the abstract class show up in my concrete classes in the API, but it won't happen in the abstract class is marked 'internal'. Is there a way to do this -- seems like the only work around is making my base class public.
Posted by Van Nostrand | September 5, 2006 6:12 PM
Posted on September 5, 2006 18:12
Sorry, a bit of clarification. "I would like to have the methods of the abstract class show up in my concrete classes in the *DOCS*"
Posted by Van Nostrand | September 5, 2006 6:15 PM
Posted on September 5, 2006 18:15
Sorry, a bit of clarification. "I would like to have the asdoc comments for the methods of the abstract class show up in my concrete classes in the *DOCS* -- the way they do if the base class is public"
Posted by Van Nostrand | September 5, 2006 6:16 PM
Posted on September 5, 2006 18:16
Jürgen, your bug and enhancement requests are now in our bug tracker.
Van Nostrand, the internal issue sounds like a bug and will be logged. As for the overriding class question, try @copy or @inheritDoc, as described here:
http://labs.adobe.com/wiki/index.php/ASDoc:Creating_ASDoc_Comments#ASDoc_Tags
Posted by Brian Deitte | September 10, 2006 8:38 PM
Posted on September 10, 2006 20:38
I have a general problem. Labs says "ASDoc uses the first sentence to populate the member summary table at the top of the HTML page". This is no problem at all but is there a way to exclude the summary from the description?
It is sometimes a little bit unaesthetic if you have that short summary sentence in front of a very detailed description.
Posted by joa | October 2, 2006 7:21 AM
Posted on October 2, 2006 07:21
jos, there's no built-in way to do this. If you ask for this on the wish form, however, we can consider this for a future release:
http://www.adobe.com/cfusion/mmform/index.cfm?name=wishform
If you'd like to try to do this yourself in an unsupported and unofficial way, you can edit the XSL files in the asdoc/templates directory. These XSL files create the HTML output and normally shouldn't be edited but can be if you really want to. The summary will be found in the XSL as "shortDescription". It's in there in quite a few places, so you'd have to figure out for yourself which reference to remove.
Posted by Brian Deitte | October 2, 2006 11:27 AM
Posted on October 2, 2006 11:27
Hi Brian!
It's a great support for all flex developers around the world~*
By the way, does ASDOC support Korean AS tags also? I've tried it for a bunch of AS classes commented in Korean and just come up with some weird set of characters.
For your reference, I made the batch file something like
..\..\bin\asdoc -source-path test -doc-sources test\. -main-title "Utils API Documentation" -actionscript-file-encoding=euc-kr -window-title "utils API Documentation" -package kr.co.riasoft.utils "Utils libraries" -output utils-asdoc
any ideas?
Thanks in advance!
Posted by joshy | October 12, 2006 6:28 AM
Posted on October 12, 2006 06:28
joshy, it's a known issue that ASDoc has issues with UTF-8 characters. This is fixed locally and will be available in the next update to Flex, which will include ASDoc.
Posted by Brian | October 12, 2006 4:10 PM
Posted on October 12, 2006 16:10
Brian, it's good to hear. I'm waiting for releasing the next update to Flex including ASDoc. Thanks.
Posted by sato-shi | October 16, 2006 5:47 AM
Posted on October 16, 2006 05:47
Brian, I had some problems when trying to generate the doc of my project using ASDoc. I got similar errors to the compiler ones when running ASDoc but my app compiles and runs properly on Flex. The first error is 'Definition es.vicentepastor.graficos.formularios:DatosInterfaz could not be found.' with references to an import statement. This class 'DatosInterfaz' is implemented as a MXML component derived from 'TitleWindow' and is properly imported, used and run on my app. This error happens in my code 4 times. I continue the post separately for not making this one too long.
Posted by Vicente Pastor | October 28, 2006 10:30 AM
Posted on October 28, 2006 10:30
Brian, Another error I am receiving when using ASDoc is 'Type was not found or was not a compile-time constant'. These errors are happening when using a MXML component developed by me into another MXML component using the corresponding tag and when the package is properly configured on the xmlns parameter. As with the previous error, the app compiles, uses and runs such components without any problem.
Posted by Vicente Pastor | October 28, 2006 10:47 AM
Posted on October 28, 2006 10:47
Brian, I also receive the following error when running ASDoc against my project: 'Error: Call to a possibly undefined method Host.'. Host is not a method. It is an AS3 class developed by me. It is used in the code for casting the result obtained when referencing an element of an Array. As before the code is perfectly working in my app.
Posted by Vicente Pastor | October 28, 2006 10:53 AM
Posted on October 28, 2006 10:53
I'm running in to the problem of ASdoc not allowing spaces in OSX. The docs on adobe labs says to use load-config to workaround this. Does anyone have a sample config file? Is there any documentation on the syntax this config file should have?
Posted by Jay Alder | October 31, 2006 5:35 PM
Posted on October 31, 2006 17:35
Vicente, try adding a "source-path" to your asdoc command. You'll need one that references the parent of the "es" directory. The other two problems you mentioned seem to be the same thing, classes that can't be found because they aren't in the source-path.
Jay, the file "bin/asdoc" is a simple shell script. If you look at it, you may be able to figure out what's wrong. You could also download the full Flex version for Mac on labs and look at "bin/mxmlc". I bet there's differences between the mxmlc and asdoc scripts.
Posted by Brian Deitte | November 5, 2006 1:15 PM
Posted on November 5, 2006 13:15
My team has recently introduced MDM Zinc into our application to access the user's local filesystem. I am not sure how to tell ASDoc to either import or ignore the MDM references. Because of this, I can no longer document our project. (I tried using the -exclude-dependencies flag, but that didn't seem to do much.)
We have had similar difficulties with external embedded resources such as fonts.
cheers!
brian
Posted by brian vaughn | November 7, 2006 2:34 PM
Posted on November 7, 2006 14:34
Brian, ASDoc still needs to compile the application, so MDM Zinc references need to be imported in the same way as they would be for a normal compilation. Otherwise you'll get compilation errors.
As for embedded resources, the embedded resources need to be around (as they normally would need to be for a compilation), but this will be fixed in the next release.
Posted by Brian Deitte | November 7, 2006 11:17 PM
Posted on November 7, 2006 23:17
Hi Brian, maybe not the right place.. but here goes.. I have the problem that when I run a ANT file in Eclipse which builds the ASDOCS. I get the following->
Error: Unable to locate specified base class 'mx.core.Application' for component class class 'flickrFolio'
Posted by Nyls | November 17, 2006 8:37 AM
Posted on November 17, 2006 08:37
Nyls, this isn't an ASDoc problem but a problem with your parameters for ASDoc in Ant. Post your Ant commands on flexcoders or the Flex forums and you should get this figured out.
Posted by Brian Deitte | November 17, 2006 7:43 PM
Posted on November 17, 2006 19:43
A small utility that can fix (at least some of) the non-ASCII irregularities in asdoc-generated HTMLs
http://ish.corbina.ru/asdocfix/asdocfix.jar.zip
Posted by ish-west | December 14, 2006 7:58 AM
Posted on December 14, 2006 07:58
ish-west, thanks for sharing this. Note that the non-ASCII problems will also be fixed in the next update to Flex.
Posted by Brian Deitte | December 15, 2006 11:15 AM
Posted on December 15, 2006 11:15
Hi Brian,
quite new to asdoc I run into following problem:
asdoc -arg -arg ... shows following text :
Error: could not find a JVM.
I have different JVM installed . I entered the path to my 'base' jvm inside my program files .
Why doesnt asdoc recognize Flex's internally set jvm ?
Where is my fault ?
Thanx for reply ^^
Amir
Posted by amir | December 22, 2006 9:07 AM
Posted on December 22, 2006 09:07
amir, did you edit "jvm.config" with different settings for your JVM? You must also edit "asdoc_jvm.config" for ASDoc.
Posted by Brian Deitte | December 26, 2006 10:55 AM
Posted on December 26, 2006 10:55
Brian,
I got the config file route to work around the whitespace issue for OS X, but it doesn't seem to work with package descriptions. I get this error "Error: unknown configuration variable 'package'". I take it the XML parser doesn't know about the package tag? That is too bad because that is where most of the whitespace will be. Unless I am doing something wrong OS X users will have to wait for a complete asdoc.
Posted by Jay Alder | December 29, 2006 5:38 PM
Posted on December 29, 2006 17:38
Jay, do you mean you have "package" in an XML configuration file and it can't be found? Note that you must put this inside a "packages" element:
<packages>
<package>foobar</package>
<packages>
Posted by Brian Deitte | December 31, 2006 11:39 AM
Posted on December 31, 2006 11:39
Brian,
When you use the [Managed] metadata tag it seems that ASDOC does not include the properties defined as getters/setters for the class. It does include the properties for the super. I thought it might be similar to the known issue with the [Bindable] metadata tag but I could not prove it. Is this also a known issue or am I perhaps doing something wrong?
Posted by Ron Jensen | January 9, 2007 1:15 PM
Posted on January 9, 2007 13:15
Brian,
When I tried:
<packages>
<package>MyPackage MyDescription</package>
</packages>
asdoc gave me this error:
Error: configuration variable 'packages.package' expected 2 argument(s), got 0
Are they supposed to be attributes rather than children? Is there any documentation on the xml syntax or maybe a working sample config file?
Posted by Jay Alder | January 9, 2007 8:36 PM
Posted on January 9, 2007 20:36
Ron, this could be because of compiler changes that the compiler makes when the Managed metadata is used, but I'm not sure. Have you tried 2.01? This may work in the newer version.
Jay, you can get the subelement names through "asdoc -help element-name". Try this:
<packages>
<package>
<string>MyPackage</string>
<string>MyDescription</string>
</package>
</packages>
Posted by Brian Deitte | January 14, 2007 4:36 PM
Posted on January 14, 2007 16:36