Eric Feminella

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.

Most ActionScript developers are very familiar with Anonymous Objects in ActionScript 3.0 as they provide a convenient mechanism from which properties of an object which are not known at design time can be defined at runtime. This post is just a quick tip on the Object.setPropertyIsEnumerable() method, for more detailed information on using Objects in ActionScript 3.0 visit livedocs.

The Object class has a few useful methods, specifically toString();, hasOwnProperty(); and propertyIsEnumerable();. There is also another method of the Object class which is very useful: setPropertyIsEnumerable() which can be utilized to explicitly omit a property from being included in an enumeration of an object.

Consider the following example:

When enumerating the object instance all properties and their values can easily be retrieved, however it is important to keep in mind that when enumerating an Object the order in which properties are retrieved is not guaranteed. So executing the same loop against the same object instance could yield different results each time, such as “value B, value A, value C” as opposed to what you might have expected, i.e. “value A, value B, value C”.

Now suppose you do not want a property to be exposed via an enumeration of the object, this can be achieved via:

So based on the above examples, if we did not want to expose the “propA” property in a for in… loop we could omit the property as follows:

So when you need to omit properties from being included in an enumeration of an object, Object.setPropertyIsEnumerable(); proves very useful.

Here’s a quick tip you won’t find easily on live docs…

Yesterday I found myself needing to embed assets in a .properties file (ResourceBundle) however after looking through the Flex documentation I wasn’t completely satisfied with the examples that were available. So I tried something pretty simple and it works perfectly.

To embed an external asset such as an image, audio file, font etc you need only specify an embed directive just as one normally would for an asset, and the file will be embedded in the application. This approach is very much like using the embed directive to embed assets in CSS but only with properties files instead.

For example, suppose you wanted to embed an image named, “image.jpg” using a properties file. To do so simply define the image as follows:

Then to display the embedded image simply reference the class object to which it has been embedded as follows:

And that’s it. Same applies for all embedded assets. I also provided a quick example as well – complete with my son Anthony on the Piano!.