NaturalDocs is very nice and it supports a wide variety of languages. However I didn’t like how it documented inherited properties and methods.
I then turned to ASDoc. ASDoc is part of the Flex SDK, and it’s what the big guys at Adobe use.
Documenting Flex projects is “easy”. However there’s not too much documentation around for using ASDoc with the Flash IDE. I had a hard time making it work the first time I tried it, so here’s a list of tips I’d like to share to make your ASDoc experience less painful.
First of all, there’s running the ASDoc command. While you can run the asdoc command through the console, write a shell script or a rake task, I recommend ASDocr. ASDocr gives you a nice GUI to run the command. You just need to point the location of the asdoc command and the sourche path of your project and your are ready to go.
Is very unlikely you’ll succeed the first time. Why? ASDoc fails if it find errors in your code, that includes all of those classes that are not being compiled (and thus the Flash IDE doesn’t wanr you). So take all those files out and try it again.
Second is dependencies. The Flash IDE creates a lot of stuff on the background so you don’t have to care for it. Remember the “A definition for this class could not be found in the classpath, so one will be automatically generated in the SWF file upon export” message? Well, ASDoc will look for those classes but they won’t be on your classpath, so it fails. The solution, create a class for every one of the symbols you export for Actionscript.
You also have to deal with symbols with instance names. Normally you can access these symbols in your class by using the instance name. The Flash IDE creates a property inside your object so the symbol can be fetched from that property. That’s why you can’t have a method and a symbol with the same name/instance. ASDoc doesn’t know about these magic properties and fails. To solve this issue use getChildByName instead.
this.my_symbol_instance_name //change this
this.getChildByName("my_symbol_instance_name") //to this
I usually name symbols on the stage with an appended underscore (_my_symbol_instance_name) and save into a private variable (private var my_symbol_instance_name:DisplayObject).
It’s important to know that getChildByName will throw an error if it doesn’t find a symbol, so you’ll want to wrap it inside a try…catch..finally block then.
And finally comes the libraries. ASDoc only recognizes .swc files or directories containing .swc files as the library-path. Use the .swc packaged version of your libraries (if available) or create your own. Creating .swc files with the Flash IDE is a little bit tricky too, take a look here for more information.
I haven’t found any more things preventing my code from bein documented with ASDoc, if you find anything else feel free to comment. I also haven’t been able to run ASDoc with the FLVPlayer component, I use the wildcard so it doesn’t look for the class definition.
Documenting your Flash IDE project with ASDoc
So, you want to generate some documentation for your project?
I’ve found two great options: NaturalDocs and ASDoc.
NaturalDocs is very nice and it supports a wide variety of languages. However I didn’t like how it documented inherited properties and methods.
I then turned to ASDoc. ASDoc is part of the Flex SDK, and it’s what the big guys at Adobe use.
Documenting Flex projects is “easy”. However there’s not too much documentation around for using ASDoc with the Flash IDE. I had a hard time making it work the first time I tried it, so here’s a list of tips I’d like to share to make your ASDoc experience less painful.
First of all, there’s running the ASDoc command. While you can run the asdoc command through the console, write a shell script or a rake task, I recommend ASDocr. ASDocr gives you a nice GUI to run the command. You just need to point the location of the asdoc command and the sourche path of your project and your are ready to go.
Is very unlikely you’ll succeed the first time. Why? ASDoc fails if it find errors in your code, that includes all of those classes that are not being compiled (and thus the Flash IDE doesn’t wanr you). So take all those files out and try it again.
Second is dependencies. The Flash IDE creates a lot of stuff on the background so you don’t have to care for it. Remember the “A definition for this class could not be found in the classpath, so one will be automatically generated in the SWF file upon export” message? Well, ASDoc will look for those classes but they won’t be on your classpath, so it fails. The solution, create a class for every one of the symbols you export for Actionscript.
You also have to deal with symbols with instance names. Normally you can access these symbols in your class by using the instance name. The Flash IDE creates a property inside your object so the symbol can be fetched from that property. That’s why you can’t have a method and a symbol with the same name/instance. ASDoc doesn’t know about these magic properties and fails. To solve this issue use getChildByName instead.
this.my_symbol_instance_name //change this this.getChildByName("my_symbol_instance_name") //to thisI usually name symbols on the stage with an appended underscore (_my_symbol_instance_name) and save into a private variable (private var my_symbol_instance_name:DisplayObject).
It’s important to know that getChildByName will throw an error if it doesn’t find a symbol, so you’ll want to wrap it inside a try…catch..finally block then.
And finally comes the libraries. ASDoc only recognizes .swc files or directories containing .swc files as the library-path. Use the .swc packaged version of your libraries (if available) or create your own. Creating .swc files with the Flash IDE is a little bit tricky too, take a look here for more information.
I haven’t found any more things preventing my code from bein documented with ASDoc, if you find anything else feel free to comment. I also haven’t been able to run ASDoc with the FLVPlayer component, I use the wildcard so it doesn’t look for the class definition.