A feature of the Flex SDK is that you can mark deprecated classes and methods via the [Deprecated] metadata tag. The goal of deprecating code is to inform developers that code will disappear in an upcoming release of a library or framework. Developers can then change their code to use the appropriate replacement and prevent problems when upgrading to newer versions. For more info, read How and When to Deprecate APIs.
The need for deprecation comes about because, as a class evolves, its API changes. Methods are renamed for consistency. New and better methods are added. Attributes change. But making such changes introduces a problem. You need to keep the old API around until people make the transition to the new one, but you don't want developers to continue programming to the old API.
Here's an example:
-
package org.as3commons.reflect {
-
-
[Deprecated(replacement="org.as3commons.lang.ClassUtils", since="1.1")]
-
public class ClassUtils {
-
-
[Deprecated(replacement="org.as3commons.lang.ClassUtils.forInstance()", since="1.1")]
-
public static function forInstance(instance:*, applicationDomain:ApplicationDomain = null):Class {
-
// ... method body ommitted
-
}
-
}
-
}
Depending on the IDE you are using, you will even get visual hints when you are using deprecated code. Here's how IntelliJ IDEA supports this. (Click to enlarge)
Note that I'm using an early build of the upcoming version 9 of IntelliJ IDEA, codenamed "Maia", in which Flex support has significantly been improved. You can get the prereleases here.
You can also use this on other metadata tags such as Style, but in a slightly different form:
-
[Style(name="backgroundColor", type="uint", format="Color", inherit="no", deprecatedReplacement="swatchPanelStyleName", deprecatedSince="3.0")]
For more info on the [Deprecated] metadata tag, see the Flex documentation.
I haven't tested how deprecations are handled in Flex/Flash Builder and the ASDoc system. If anyone knows, don't hesitate to add extra info in the comments and I will update this post.
Update The [Deprecated] metadata tag was posted about some time ago in this blogpost, which made me believe it was undocumented or at least it was at the time of writing. Thanks to Bobby Parker for posting the link to the Flex 3 docs in which the metadata is clearly documented.
Add to Bloglines - Digg This! - del.icio.us - Stumble It! - Twit This! - Technorati links - Share on Facebook - Feedburner
Christophe Herreman is a software developer living in Belgium. He's working on high-end Flex and AIR solutions at 
September 12th, 2009 at 3:18 pm
I have to take issue with your statement of “undocumented”.
It’s most certainly documented. It’s documented here: http://livedocs.adobe.com/flex/3/html/metadata_3.html#172179
I’m not meaning to sound snarky or anything, but I just find it odd that you would make such a claim when the information on this is readily available.
September 12th, 2009 at 3:42 pm
Thanks Bobby. I actually didn’t know it was documented that way. I must have been mislead by the blogpost I found when googling around for the Deprecated metadata. I’ll update my post with the info you provided.
September 12th, 2009 at 4:35 pm
Cool beans! Blogs are nice for some things, but I’ve seen often that things claimed to be “undocumented”, actually ARE documented, just often enough, not where one might expect them to be.
September 15th, 2009 at 1:14 am
I believe there was a time when Deprecated metadata was undocumented, possibly when Flex was still version 2, and possibly even in earlier releases of Flex 3. There was a lot of metadata that was undocumented for a long time.