From 948d48e8402492ba17c6c47abe2c39c58f7e04b2 Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sat, 31 Mar 2018 12:09:10 +0200 Subject: [PATCH 1/4] 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. --- src/libstd/error.rs | 54 +++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 3d0c96585b552..16341768725e3 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,7 +35,31 @@ 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`]. 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")] pub trait Error: Debug + Display { /// A short description of the error. From 0b5cc197d79b961d94edb4427276e595f714447d Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sat, 31 Mar 2018 12:10:18 +0200 Subject: [PATCH 2/4] Remove code definition of the Error trait from its doc-comment It was out of date, and rustdoc already shows the same information. --- src/libstd/error.rs | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 16341768725e3..ea6a85f747d97 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -40,16 +40,6 @@ use string; /// 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 From 03f46ad359272eaeee8873441103538a31214161 Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sat, 31 Mar 2018 12:12:21 +0200 Subject: [PATCH 3/4] 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. --- src/libstd/error.rs | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index ea6a85f747d97..14fcd7e4dd027 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -52,30 +52,29 @@ use string; /// [`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 2fc466819cc39e23773677fe675f0074f25e0f0e Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sat, 31 Mar 2018 12:18:11 +0200 Subject: [PATCH 4/4] Tweak Error trait docs to reflect actual requirements --- src/libstd/error.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 14fcd7e4dd027..6812953e0f117 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -36,9 +36,9 @@ use str; use string; /// `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: +/// 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"