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 commit:

- 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.

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 {}

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

src/librustc_errors/lib.rs

@@ -251,11 +251,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, SubDiagnostic, DiagnosticStyledString, DiagnosticId};
 pub use diagnostic_builder::DiagnosticBuilder;

src/librustc_mir/const_eval.rs

@@ -199,18 +199,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",
-        }
-    }
-
-    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> {

src/librustdoc/html/render.rs

@@ -100,11 +100,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 {

src/libserialize/hex.rs

@@ -69,15 +69,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 `~`)

src/libserialize/json.rs

@@ -338,9 +338,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 {
@@ -349,9 +347,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`

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()
     }