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.

2 files changed, 6 insertions, 8 deletions

diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index 3ba80e76672..fee5a4e102b 100644
--- a/src/libstd/io/buffered.rs
+++ b/src/libstd/io/buffered.rs
@@ -752,6 +752,7 @@ impl<W> From<IntoInnerError<W>> for Error {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<W: Send + fmt::Debug> error::Error for IntoInnerError<W> {
+    #[allow(deprecated, deprecated_in_future)]
     fn description(&self) -> &str {
         error::Error::description(self.error())
     }
diff --git a/src/libstd/io/error.rs b/src/libstd/io/error.rs
index efe839d1302..3b55d9b9002 100644
--- a/src/libstd/io/error.rs
+++ b/src/libstd/io/error.rs
@@ -534,6 +534,7 @@ impl fmt::Display for Error {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl error::Error for Error {
+    #[allow(deprecated, deprecated_in_future)]
     fn description(&self) -> &str {
         match self.repr {
             Repr::Os(..) | Repr::Simple(..) => self.kind().as_str(),
@@ -603,22 +604,18 @@ mod test {
         struct TestError;
 
         impl fmt::Display for TestError {
-            fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result {
-                Ok(())
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                f.write_str("asdf")
             }
         }
 
-        impl error::Error for TestError {
-            fn description(&self) -> &str {
-                "asdf"
-            }
-        }
+        impl error::Error for TestError {}
 
         // we have to call all of these UFCS style right now since method
         // resolution won't implicitly drop the Send+Sync bounds
         let mut err = Error::new(ErrorKind::Other, TestError);
         assert!(err.get_ref().unwrap().is::<TestError>());
-        assert_eq!("asdf", err.get_ref().unwrap().description());
+        assert_eq!("asdf", err.get_ref().unwrap().to_string());
         assert!(err.get_mut().unwrap().is::<TestError>());
         let extracted = err.into_inner().unwrap();
         extracted.downcast::<TestError>().unwrap();