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.

9 files changed, 9 insertions, 0 deletions

diff --git a/src/libstd/sys/cloudabi/shims/os.rs b/src/libstd/sys/cloudabi/shims/os.rs
index 944b9525b3b..779e6d54b7c 100644
--- a/src/libstd/sys/cloudabi/shims/os.rs
+++ b/src/libstd/sys/cloudabi/shims/os.rs
@@ -63,6 +63,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "not supported on CloudABI yet"
     }
diff --git a/src/libstd/sys/hermit/os.rs b/src/libstd/sys/hermit/os.rs
index ad63b0e0c13..5999fdd4f8d 100644
--- a/src/libstd/sys/hermit/os.rs
+++ b/src/libstd/sys/hermit/os.rs
@@ -61,6 +61,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "not supported on hermit yet"
     }
diff --git a/src/libstd/sys/sgx/net.rs b/src/libstd/sys/sgx/net.rs
index f36687b4d3d..bd0652ab464 100644
--- a/src/libstd/sys/sgx/net.rs
+++ b/src/libstd/sys/sgx/net.rs
@@ -440,6 +440,7 @@ pub struct NonIpSockAddr {
 }
 
 impl error::Error for NonIpSockAddr {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "Failed to convert address to SocketAddr"
     }
diff --git a/src/libstd/sys/sgx/os.rs b/src/libstd/sys/sgx/os.rs
index 2c5b3134219..6ed7a2f2044 100644
--- a/src/libstd/sys/sgx/os.rs
+++ b/src/libstd/sys/sgx/os.rs
@@ -66,6 +66,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "not supported in SGX yet"
     }
diff --git a/src/libstd/sys/unix/os.rs b/src/libstd/sys/unix/os.rs
index 95be564b330..b0b14725344 100644
--- a/src/libstd/sys/unix/os.rs
+++ b/src/libstd/sys/unix/os.rs
@@ -213,6 +213,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "failed to join paths"
     }
diff --git a/src/libstd/sys/vxworks/os.rs b/src/libstd/sys/vxworks/os.rs
index b37a1790454..3f207cabf97 100644
--- a/src/libstd/sys/vxworks/os.rs
+++ b/src/libstd/sys/vxworks/os.rs
@@ -173,6 +173,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "failed to join paths"
     }
diff --git a/src/libstd/sys/wasi/os.rs b/src/libstd/sys/wasi/os.rs
index 338fbe89765..44a08a2f058 100644
--- a/src/libstd/sys/wasi/os.rs
+++ b/src/libstd/sys/wasi/os.rs
@@ -78,6 +78,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "not supported on wasm yet"
     }
diff --git a/src/libstd/sys/wasm/os.rs b/src/libstd/sys/wasm/os.rs
index 193c3892743..91afdc8a5a0 100644
--- a/src/libstd/sys/wasm/os.rs
+++ b/src/libstd/sys/wasm/os.rs
@@ -53,6 +53,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "not supported on wasm yet"
     }
diff --git a/src/libstd/sys/windows/os.rs b/src/libstd/sys/windows/os.rs
index 8631e50cf38..e0a1d2f4c0e 100644
--- a/src/libstd/sys/windows/os.rs
+++ b/src/libstd/sys/windows/os.rs
@@ -225,6 +225,7 @@ impl fmt::Display for JoinPathsError {
 }
 
 impl StdError for JoinPathsError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "failed to join paths"
     }