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:

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:

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.