Rust: Tracking issue for `#[deprecated]`

[alexcrichton]

Tracking issue for https://github.com/rust-lang/rfcs/pull/1270

[llogiq]

So should we

• [ ] rename the current rustc-internal feature
• [ ] extends and change the feature so it works (unstably) outside of rustc?

[huonw]

Renaming may help ensure there's no accidental contamination of the stable one with any new features in the internal one.

[llogiq]

OK, I'll see if I find the time to whip up a PR to rename #[deprecated] to #[rustc_deprecated].

[petrochenkov]

@llogiq

OK, I'll see if I find the time to whip up a PR to rename #[deprecated] to #[rustc_deprecated]

I'll go ahead and do it right now if you do not mind.
(I'm currently doing some work with stability anyway)

[llogiq]

Fine with me.

[bluss]

#[deprecated] is great, but still unstable! Can we stabilize it soon? I'm putting it to use where possible.

I am reopening this as the tracking issue should be open until it's stable.

[petrochenkov]

Oh, by the way, #[deprecated] on a module (or any other item) is inherited by all the child items of that module.
This behavior is reasonable and it's inherited from #[rustc_deprecated] and other stability attributes, but it was never discussed explicitly, AFAIR.
One minor drawback of this behavior is that items inside of deprecated modules can't be "undeprecated".

[alexcrichton]

:bell: This issue is now entering its cycle-long final comment period for stabilization in 1.9 :bell:

A question to consider as part of FCP is that you can't selectively allow deprecations, only blanket allow deprecations. This is somewhat unfortunate as you frequently just want to allow usage of one deprecated API, but not necessarily all.

[jonas-schievink]

@alexcrichton When attributes on statements and expression are stable (and the current #[allow] logic is fixed), you could just allow a single use of a deprecated item

[alexcrichton]

@jonas-schievink indeed! One problem with that though is if I have widespread usage of one API in my program I'd have to tag lots of places as #[allow] :(

An example is that in the past Cargo was trying to support super old Rust versions, and one notable part of that was the deprecation of str::connect in favor of str::join, where Cargo called connect quite a bit. This ended up meaning that #[allow(deprecated)] had to be put in lots of places :(

[llogiq]

One partial solution is to write a non-deprecated wrapper around the deprecated API and redact usage to use the wrapper. Of course this is tedious.

[huonw]

A question to consider as part of FCP is that you can't selectively allow deprecations, only blanket allow deprecations. This is somewhat unfortunate as you frequently just want to allow usage of one deprecated API, but not necessarily all.

Easy targeted allows is the sticking point for me, e.g. people are able to stick an attribute at the top of a crate, rather than at every usage, or writing their own wrappers. Without that, it seems like widespread usage of #[deprecated] by library authors (a good thing!) would result in a lot of crates with #[allow(deprecated)] due to one dependency. This would dramatically weaken the utility of deprecated: any crate with that allow would get no new deprecation warnings even from crates that they did not originally need the allow for.

(For that reason, maybe we want to deprecate #[allow(deprecated)] once we have targeted allows, either removing that blanket allow functionality, or at least making it more explicit?)

[bluss]

I've only had to put allow(deprecated) on use lines and the actual methods where I used the deprecated items. That was pretty well scoped.

[jan-hudec]

Actually I would consider a better option to normally keep the warnings, but report each deprecated symbol only once. That would make it short enough to notice any new warnings while keeping it up as a reminder that something needs to be done about it.

[hoodie]

isn't that already the case?

[alexcrichton]

The libs team discussed this during triage yesterday and the decision was to stabilize.

We discussed @huonw's concern but we felt that this has been waiting long enough and the situation isn't _bad enough_ that we should hold off stabilization.

[vityafx]

I have just deprecated a function and now whenever I invoke cargo test --doc, the code example in the doc comment for this function gives me a warning. I wonder, is there any sense in this? I would disable printing deprecation warning in the doc comments of the function which has been deprecated.

[llogiq]

That would quell deprecation warnings from other places, which would then fly under the radar.

The optimum solution would be to create an annotation that works as allow(deprecation) but only for deprecated items within the current module. We could then extend rustdoc to search for deprecation annotations and add this restricted allow annotation to the doctest item.

[vityafx]

That would quell deprecation warnings from other places, which would then fly under the radar.

The optimum solution would be to create an annotation that works as allow(deprecation) but only for deprecated items within the current module. We could then extend rustdoc to search for deprecation annotations and add this restricted allow annotation to the doctest item.

Sounds legit.