Flex Quick Tip: ASDoc Package comments

Documenting ActionScript elements such as a Class, Interface, method, property, event, style and so forth with ASDoc is a rather simple and straightforward process. However one element which is a bit more tricky to document with ASDoc is package declarations.

Determining how to document package declarations is a bit more complicated than say, documenting classes as there is not a specific ASDoc tag intended for documenting packages in source code form. To do so one might assume to simply add an ASDoc comment to a package declaration, such as the following:

However the above will not generate ASDoc source documentation; it will simply be ignored by the asdoc compiler.

In order to document packages you need to specify the -package argument to the asdoc compiler. This is specified in the form:
-package <package-name> '<package-comment>

In general, I think most developers would prefer not to specify any kind of source file documentation via a compiler argument as this type of metadata ideally should be defined as an annotation (in the documentation sense of the word) to the actual source file itself, however if you find a need to document packages the -package compiler option will do the job.

{ 5 comments to read ... please submit one more! }

  1. Eric,
    Thanks for the tip. I was wondering for a long time how Adobe pulled it off to have package level documentation.
    Cheers
    Daniel

    P.S. I’ll use it in http://docs.openzoom.org/

  2. If you check out the file Overviews_Base.xml in the default ASDoc template, you’ll see some interesting XML commented out that might explain another way to document packages. The top comment says “this file normally should not be edited. Use the command-line parameters for ASDoc instead”, but I’m guessing Adobe’s official templates include the package descriptions in this file rather than using command line arguments. Purely speculation, of course. The file ASDoc_Config_Base.xml has some interesting stuff too, if anyone is interested.

  3. Hey Josh,

    Nice find. This file seems to have a some potential for configuring the asdoc compiler via a configuration file as opposed to the commandline options.

    Eric

  4. Hi,
    I don’t know if this is old news to you by now. But I just found out.
    With the Flex 4 SDK, Adobe introduced a new option for the ASDoc-Compiler.

    "-package-description-file myPackages.xml"

    It lets you specify a package description file in the following format.

    Cheers
    Florian

{ 0 Pingbacks/Trackbacks }