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)

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