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)

1 files changed, 5 insertions, 0 deletions

diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs
index 2831bbcb88d..0e334c191e7 100644
--- a/src/libstd/sync/mpsc/mod.rs
+++ b/src/libstd/sync/mpsc/mod.rs
@@ -1550,6 +1550,7 @@ impl<T> fmt::Display for SendError<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Send> error::Error for SendError<T> {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "sending on a closed channel"
     }
@@ -1577,6 +1578,7 @@ impl<T> fmt::Display for TrySendError<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Send> error::Error for TrySendError<T> {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         match *self {
             TrySendError::Full(..) => "sending on a full channel",
@@ -1603,6 +1605,7 @@ impl fmt::Display for RecvError {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl error::Error for RecvError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         "receiving on a closed channel"
     }
@@ -1620,6 +1623,7 @@ impl fmt::Display for TryRecvError {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl error::Error for TryRecvError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         match *self {
             TryRecvError::Empty => "receiving on an empty channel",
@@ -1649,6 +1653,7 @@ impl fmt::Display for RecvTimeoutError {
 
 #[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")]
 impl error::Error for RecvTimeoutError {
+    #[allow(deprecated)]
     fn description(&self) -> &str {
         match *self {
             RecvTimeoutError::Timeout => "timed out waiting on channel",