Add support for #[deprecated] attribute

[brson]

Usage of items tagged with #[deprecated] should generate a warning at compile time. To make this really work correctly we'll need to write item attributes to the crate metadata.

[eholk]

I was just thinking this would be a good idea. Would there also be a way to mark entire modules as deprecated?

[graydon]

Yes. It should also take arguments that explain the deprecation and/or point to a symbol to use instead.

[brson]

I think this is unblocked and we do write attributes to item metadata now.

[brendanzab]

It'd be great if tagged items would also show up in generated documentation. D does a great job of this, highlighting the feature in red, giving a date on which the item will be dropped and pointing to an alternative item that should be used instead.

Example:

deprecated alias FormatError;
Deprecated. It will be removed In January 2013. Please use FormatException instead.

This kind of metadata could even show up in the warning at compile time. It'd be very useful for quickly updating old code.

[jesse99]

Also need to update the reference manual.

[pnkfelix]

Not critical for 0.6; de-milestoning

[pnkfelix]

(also, from looking at #4643, it sounds like this feature was backed out; not sure if that issue needs to be reopened.)

[graydon]

nominating for backwards compatible. not strictly needed but seems like it'd be helpful.

[brson]

cc #6508

[graydon]

accepted for backwards-compatible milestone

[brendanzab]

This would be very useful for cleaning up std::vec and std::str.

[brson]

Per #6875 I want support for at least #[deprecated], #[experimental], #[unstable], #[stable], and maybe eventually #[frozen] and #[locked].

[emberian]

Once the attributes are supported, it will be easy to use with rustdoc_ng