Can I mark a function as deprecated?

Question

I'd like to mark functions/methods as deprecated. I tried to apply the deprecated attribute:

#[deprecated]
fn old_way_of_doing_it() {

but this yields an error:

error: stability attributes may not be used outside of the standard library

Is there a way in which I can have the compiler warn a consumer of my library that a function is deprecated?

I have no experience, but I'm considering experimenting with compiler plugins and custom attributes, but I guess that would require the consumer to also use the plugin, which is maybe unreasonable (or may be an unreasonable amount of work for me to implement?)

As a side question out of curiosity, why is the deprecated attribute only applicable to the standard library?

Answer 1

Since Rust 1.9.0 (2016 May 26th) you can use the #[deprecated] attribute in your own crates (RFC 1270). The syntax is:

#[deprecated(since="0.5.0", note="please use `new_method` instead")]
pub fn old_method() { ..; }

It will throw the following warning whenever you use old_method:

<anon>:6:5: 6:15 warning: use of deprecated item: please use `new_method` instead, #[warn(deprecated)] on by default
<anon>:6     old_method()
             ^~~~~~~~~~

You may find more information in the RFC.

Answer 2

Update: #[deprecated] is currently (as of February 2016) available in nightly. It should be available in stable around about the beginning of March 2016.

There's no way to do this in external libraries, yet.

Doing it is very desirable (I've certainly wanted it several times), but the decision was made to focus design and implementation efforts on functionality that was needed by the standard library at 1.0, and postpone optimising a design for external libraries until later. The RFC discusses it a little:

It's important to note that these stability attributes are only known to be useful to the standard distribution, because of the explicit linkage to language versions and release channels. [...]. A general mechanism for indicating API stability will be reconsidered in the future.

[...]

With respect to stability attributes and Cargo, the proposed design is very specific to the standard library and the Rust compiler without being intended for use by third-party libraries. It is planned to extend Cargo's own support for features (distinct from Rust features) to enable this form of feature development in a first-class method through Cargo. At this time, however, there are no concrete plans for this design and it is unlikely to happen soon.

There was significant discussion on the pull request itself too:

• https://github.com/rust-lang/rfcs/pull/507#discussion-diff-22027318
• https://github.com/rust-lang/rfcs/pull/507#issuecomment-68570789 (summary comment)

(That RFC is the canonical source for information about this.)

I have no experience, but I'm considering experimenting with compiler plugins and custom attributes, but I guess that would require the consumer to also use the plugin, which is maybe unreasonable (or may be an unreasonable amount of work for me to implement?)

Yes, it would require the consumer to use the plugin, and I'm not totally sure if the compiler makes it easy for a plugin to get all the information it needs to emulate the current built-in #[deprecated].