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)

Author: bors

Diff for: src/librustc_driver/args.rs

@@ -2,7 +2,6 @@ use std::error;
 use std::fmt;
 use std::fs;
 use std::io;
-use std::str;
 
 pub fn arg_expand(arg: String) -> Result<Vec<String>, Error> {
     if arg.starts_with("@") {
@@ -36,8 +35,4 @@ impl fmt::Display for Error {
     }
 }
 
-impl error::Error for Error {
-    fn description(&self) -> &'static str {
-        "argument error"
-    }
-}
+impl error::Error for Error {}

Diff for: 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 => ...,
+    _ => ...,
 }
 ```
 

Diff for: src/librustc_errors/lib.rs

@@ -253,11 +253,7 @@ impl fmt::Display for ExplicitBug {
     }
 }
 
-impl error::Error for ExplicitBug {
-    fn description(&self) -> &str {
-        "The parser has encountered an internal bug"
-    }
-}
+impl error::Error for ExplicitBug {}
 
 pub use diagnostic::{Diagnostic, DiagnosticId, DiagnosticStyledString, SubDiagnostic};
 pub use diagnostic_builder::DiagnosticBuilder;

Diff for: src/librustc_mir/const_eval.rs

@@ -197,19 +197,7 @@ impl fmt::Display for ConstEvalError {
     }
 }
 
-impl Error for ConstEvalError {
-    fn description(&self) -> &str {
-        use self::ConstEvalError::*;
-        match *self {
-            NeedsRfc(_) => "this feature needs an rfc before being allowed inside constants",
-            ConstAccessesStatic => "constant accesses static",
-        }
-    }
-
-    fn cause(&self) -> Option<&dyn Error> {
-        None
-    }
-}
+impl Error for ConstEvalError {}
 
 // Extra machine state for CTFE, and the Machine instance
 pub struct CompileTimeInterpreter<'mir, 'tcx> {

Diff for: src/librustdoc/html/render.rs

@@ -98,11 +98,7 @@ pub struct Error {
     pub error: io::Error,
 }
 
-impl error::Error for Error {
-    fn description(&self) -> &str {
-        self.error.description()
-    }
-}
+impl error::Error for Error {}
 
 impl std::fmt::Display for Error {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {

Diff for: src/libserialize/hex.rs

@@ -68,14 +68,7 @@ impl fmt::Display for FromHexError {
     }
 }
 
-impl error::Error for FromHexError {
-    fn description(&self) -> &str {
-        match *self {
-            InvalidHexCharacter(..) => "invalid character",
-            InvalidHexLength => "invalid length",
-        }
-    }
-}
+impl error::Error for FromHexError {}
 
 impl FromHex for str {
     /// Converts any hexadecimal encoded string (literal, `@`, `&`, or `~`)

Diff for: src/libserialize/json.rs

@@ -345,11 +345,7 @@ impl fmt::Display for DecoderError {
     }
 }
 
-impl std::error::Error for DecoderError {
-    fn description(&self) -> &str {
-        "decoder error"
-    }
-}
+impl std::error::Error for DecoderError {}
 
 impl fmt::Display for EncoderError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -358,11 +354,7 @@ impl fmt::Display for EncoderError {
     }
 }
 
-impl std::error::Error for EncoderError {
-    fn description(&self) -> &str {
-        "encoder error"
-    }
-}
+impl std::error::Error for EncoderError {}
 
 impl From<fmt::Error> for EncoderError {
     /// Converts a [`fmt::Error`] into `EncoderError`

Diff for: src/libstd/env.rs

@@ -284,6 +284,7 @@ impl fmt::Display for VarError {
 
 #[stable(feature = "env", since = "1.0.0")]
 impl Error for VarError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         match *self {
             VarError::NotPresent => "environment variable not found",
@@ -526,6 +527,7 @@ impl fmt::Display for JoinPathsError {
 
 #[stable(feature = "env", since = "1.0.0")]
 impl Error for JoinPathsError {
+    #[allow(deprecated, deprecated_in_future)]
     fn description(&self) -> &str {
         self.inner.description()
     }