ASDoc Notes: Tags and Excluding Classes

Some quick notes using Adobe's ASDoc tool for generating Actionscript documentation.

The Deprecated Tag

Unlike @param, @return, and @see, ASDoc doesn't use a Java-style @deprecated tag. Instead, you use one of the following metadata tag formats:

[Deprecated]
[Deprecated("message")]
[Deprecated(replacement="MethodToUseInstead")]

The problem is, when generating documentation anything with the deprecated tag is completely ignored. I was hoping for a standardized way to indicate to the reader that the class or method had fallen out of favour. Instead, I had to settle for some regular HTML-formatted text in my comment.

@inheritDoc and Getter/Setter Overrides

I discovered odd behaviour when using the @inheritDoc tag on a getter or a setter on its own. If you don't override both of them, ASDoc interprets the property as either read-only or write-only and the documentation from the superclass or interface isn't inherited at all.

So if you're using @inheritDoc, you'll have to override both the getter and the setter, if only to call its super.

/**
 * @inheritDoc
 */
override public function get radius():Number
{
  // pointless override just returns the super's implementation
  return super.radius;
}
override public function set radius(n:Number):void
{
  super.radius = n;
 
  // the reason for overriding the setter
  invalidateProperties();
}

Excluding Classes

One final nuisance with ASDoc was the class exclusion. I was compiling documentation that used the Flash component classes so I need to include them as a source. However, I didn't want them documented so I excluded them in the command line... one class at a time.

There are alternate ways of excluding classes such as putting them all in a SWC file or putting an [ExcludeClass] or @private tag in each file. However, there really should be a way of excluding entire packages from the command line.