Auto merge of #66919 - dtolnay:description, r=KodrAus

Deprecate Error::description for real

`description` has been documented as soft-deprecated since 1.27.0 (17 months ago). There is no longer any reason to call it or implement it.

This PR:

- adds `#[rustc_deprecated(since = "1.41.0")]` to `Error::description`;
- moves `description` (and `cause`, which is also deprecated) below the `source` and `backtrace` methods in the Error trait;
- reduces documentation of `description` and `cause` to take up much less vertical real estate in rustdocs, while preserving the example that shows how to render errors without needing to call `description`;
- removes the description function of all *currently unstable* Error impls in the standard library;
- marks `#[allow(deprecated)]` the description function of all *stable* Error impls in the standard library;
- replaces miscellaneous uses of `description` in example code and the compiler.

---

![description](https://user-images.githubusercontent.com/1940490/69910369-3bbaca80-13bf-11ea-94f7-2fe27a7ea333.png)

1 files changed, 15 insertions, 15 deletions

diff --git a/src/librustc_error_codes/error_codes/E0638.md b/src/librustc_error_codes/error_codes/E0638.md
index 29b7586b07b..14cd31502b6 100644
--- a/src/librustc_error_codes/error_codes/E0638.md
+++ b/src/librustc_error_codes/error_codes/E0638.md
@@ -10,23 +10,23 @@ For example, in the below example, since the enum is marked as
 on it.
 
 ```rust,ignore (pseudo-Rust)
-use std::error::Error as StdError;
-
-#[non_exhaustive] pub enum Error {
-   Message(String),
-   Other,
+#[non_exhaustive]
+pub enum Error {
+    Message(String),
+    Other,
 }
 
-impl StdError for Error {
-   fn description(&self) -> &str {
+impl Display for Error {
+    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
         // This will not error, despite being marked as non_exhaustive, as this
         // enum is defined within the current crate, it can be matched
         // exhaustively.
-        match *self {
-           Message(ref s) => s,
-           Other => "other or unknown error",
-        }
-   }
+        let display = match self {
+            Message(s) => s,
+            Other => "other or unknown error",
+        };
+        formatter.write_str(display)
+    }
 }
 ```
 
@@ -38,9 +38,9 @@ use mycrate::Error;
 // This will not error as the non_exhaustive Error enum has been matched with a
 // wildcard.
 match error {
-   Message(ref s) => ...,
-   Other => ...,
-   _ => ...,
+    Message(s) => ...,
+    Other => ...,
+    _ => ...,
 }
 ```