Merge pull request #1423 from durka/patch-1

Amend RFC 1270 to describe actual implementation

Author: alexcrichton

text/1270-deprecation.md

@@ -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,16 +73,16 @@ 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 { .. }
 ```
 
 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