From a5655b81a3bad56beaa161662177192681832532 Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sat, 31 Mar 2018 12:09:10 +0200 Subject: [PATCH 1/3] Move description of the Error trait to its own doc-comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit … rather than the module’s. Remove code definition of the Error trait from its doc-comment It was out of date, and rustdoc already shows the same information. Add a default impl for Error::description and document it as deprecated. It is redundant with Display while being much less flexible for implementors. This is only a "soft" deprecation: it is not worth the hassle of a warning to existing users. Tweak Error trait docs to reflect actual requirements --- src/libstd/error.rs | 63 +++++++++++++++++---------------------------- 1 file changed, 24 insertions(+), 39 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 749b8ccc13da6..0954649653c17 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -9,34 +9,6 @@ // except according to those terms. //! Traits for working with Errors. -//! -//! # The `Error` trait -//! -//! `Error` is a trait representing the basic expectations for error values, -//! i.e. values of type `E` in [`Result`]. At a minimum, errors must provide -//! a description, but they may optionally provide additional detail (via -//! [`Display`]) and cause chain information: -//! -//! ``` -//! use std::fmt::Display; -//! -//! trait Error: Display { -//! fn description(&self) -> &str; -//! -//! fn cause(&self) -> Option<&Error> { None } -//! } -//! ``` -//! -//! The [`cause`] method is generally used when errors cross "abstraction -//! boundaries", i.e. when a one module must report an error that is "caused" -//! by an error from a lower-level module. This setup makes it possible for the -//! high-level module to provide its own errors that do not commit to any -//! particular implementation, but also reveal some of its implementation for -//! debugging via [`cause`] chains. -//! -//! [`Result`]: ../result/enum.Result.html -//! [`Display`]: ../fmt/trait.Display.html -//! [`cause`]: trait.Error.html#method.cause #![stable(feature = "rust1", since = "1.0.0")] @@ -63,33 +35,46 @@ use num; use str; use string; -/// Base functionality for all errors in Rust. +/// `Error` is a trait representing the basic expectations for error values, +/// i.e. values of type `E` in [`Result`]. Errors must describe +/// themselves through the [`Display`] and [`Debug`] traits, and may provide +/// cause chain information: +/// +/// The [`cause`] method is generally used when errors cross "abstraction +/// boundaries", i.e. when a one module must report an error that is "caused" +/// by an error from a lower-level module. This setup makes it possible for the +/// high-level module to provide its own errors that do not commit to any +/// particular implementation, but also reveal some of its implementation for +/// debugging via [`cause`] chains. +/// +/// [`Result`]: ../result/enum.Result.html +/// [`Display`]: ../fmt/trait.Display.html +/// [`cause`]: trait.Error.html#method.cause #[stable(feature = "rust1", since = "1.0.0")] pub trait Error: Debug + Display { - /// A short description of the error. + /// **This method is soft-deprecated.** /// - /// The description should only be used for a simple message. - /// It should not contain newlines or sentence-ending punctuation, - /// to facilitate embedding in larger user-facing strings. - /// For showing formatted error messages with more information see - /// [`Display`]. + /// Although using it won’t cause compilation warning, + /// new code should use [`Display`] instead + /// and new `impl`s can omit it. /// /// [`Display`]: ../fmt/trait.Display.html /// /// # Examples /// /// ``` - /// use std::error::Error; - /// /// match "xc".parse::() { /// Err(e) => { - /// println!("Error: {}", e.description()); + /// // Print `e` itself, not `e.description()`. + /// println!("Error: {}", e); /// } /// _ => println!("No error"), /// } /// ``` #[stable(feature = "rust1", since = "1.0.0")] - fn description(&self) -> &str; + fn description(&self) -> &str { + "" + } /// The lower-level cause of this error, if any. /// From f6a833a99a76e015cae0410f20af9f3767a14911 Mon Sep 17 00:00:00 2001 From: Kornel Date: Sun, 22 Apr 2018 19:17:08 +0100 Subject: [PATCH 2/3] Suggest alternatives to Error::description() --- src/libstd/error.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 0954649653c17..817eea5eaf142 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -58,6 +58,8 @@ pub trait Error: Debug + Display { /// new code should use [`Display`] instead /// and new `impl`s can omit it. /// + /// To obtain error description as a string, use `to_string()`. + /// /// [`Display`]: ../fmt/trait.Display.html /// /// # Examples @@ -73,7 +75,7 @@ pub trait Error: Debug + Display { /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn description(&self) -> &str { - "" + "description() is deprecated; use Display" } /// The lower-level cause of this error, if any. From 1912f39e7c024f2ee5c5ea618efdcbe92590b863 Mon Sep 17 00:00:00 2001 From: Kornel Date: Sun, 22 Apr 2018 21:11:15 +0100 Subject: [PATCH 3/3] Update book submodule to pass linkchecker test --- src/doc/book | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book b/src/doc/book index b889e1e30c5e9..6237a75790cd2 160000 --- a/src/doc/book +++ b/src/doc/book @@ -1 +1 @@ -Subproject commit b889e1e30c5e9953834aa9fa6c982bb28df46ac9 +Subproject commit 6237a75790cd2e0ca22961b55f64a83319e73464