dnrops
/
rfcs
mirror of https://github.com/rust-lang/rfcs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Amend RFC 1270 to describe actual implementation 

Change `reason` to `note` and remove `use`.
This commit is contained in:
Alex Burka 2015-12-22 16:37:56 -05:00
parent 3a16a14ca5
commit b29c3f7420
1 changed files with 11 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
text/1270-deprecation.md
View File

@ -6,7 +6,7 @@
# Summary
This RFC proposes to allow library authors to use a `#[deprecated]` attribute,
with optional `since = "`*version*`"` and `reason = "`*free text*`"`fields. The
with optional `since = "`*version*`"` and `note = "`*free text*`"`fields. The
compiler can then warn on deprecated items, while `rustdoc` can document their
deprecation accordingly.
@ -32,12 +32,11 @@ possible fields are optional:
deprecating the item, following the semver scheme. Rustc does not know about
versions, thus the content of this field is not checked (but will be by external
lints, e.g. [rust-clippy](https://github.com/Manishearth/rust-clippy).
* `reason` should contain a human-readable string outlining the reason for
deprecating the item. While this field is not required, library authors are
strongly advised to make use of it to convey the reason for the deprecation to
users of their library. The string is interpreted as plain unformatted text
(for now) so that rustdoc can include it in the item's documentation without
messing up the formatting.
* `note` should contain a human-readable string outlining the reason for
deprecating the item and/or what to use instead. While this field is not required,
library authors are strongly advised to make use of it. The string is interpreted
as plain unformatted text (for now) so that rustdoc can include it in the item's
documentation without messing up the formatting.
On use of a *deprecated* item, `rustc` will `warn` of the deprecation. Note
that during Cargo builds, warnings on dependencies get silenced. While this has
@ -51,7 +50,7 @@ to warn on use of deprecated items in library crates, however this is outside
the scope of this RFC.
`rustdoc` will show deprecation on items, with a `[deprecated]` box that may
optionally show the version and reason where available.
optionally show the version and note where available.
The language reference will be extended to describe this feature as outlined
in this RFC. Authors shall be advised to leave their users enough time to react
@ -74,8 +73,8 @@ prefix to the `Foo` type:
```
extern crate rust_foo;
#[deprecated(since = "0.2.1", use="rust_foo::Foo",
reason="The rust_foo version is more advanced, and this crates' will likely be discontinued")]
#[deprecated(since = "0.2.1",
note="The rust_foo version is more advanced, and this crate's will likely be discontinued")]
struct Foo { .. }
```
@ -83,7 +82,7 @@ Users of her crate will see the following once they `cargo update` and `build`:
```
src/foo_use.rs:27:5: 27:8 warning: Foo is marked deprecated as of version 0.2.1
src/foo_use.rs:27:5: 27:8 note: The rust_foo version is more advanced, and this crates' will likely be discontinued
src/foo_use.rs:27:5: 27:8 note: The rust_foo version is more advanced, and this crate's will likely be discontinued
```
Rust-clippy will likely gain more sophisticated checks for deprecation:
@ -108,7 +107,7 @@ deprecation checks.
* make the `since` field required and check that it's a single version
* require either `reason` or `use` be present
* `reason` could include markdown formatting
* rename the `reason` field to `note` to clarify it's broader usage.
* rename the `reason` field to `note` to clarify its broader usage. (**done!**)
* add a `note` field and make `reason` a field with specific meaning, perhaps
even predefine a number of valid reason strings, as JEP277 currently does
* Add a `use` field containing a plain text of what to use instead