From 7ce8f7cfb2bd1f0737b56511e6d64db1564be387 Mon Sep 17 00:00:00 2001 From: Moritz Moeller Date: Fri, 25 Feb 2022 16:20:08 +0100 Subject: [PATCH] More doc fixes, made ErrorHook type public. --- src/eyreish/mod.rs | 49 ++++++++++++++++++++------------------- src/handlers/graphical.rs | 4 ++-- src/named_source.rs | 6 ++--- 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/src/eyreish/mod.rs b/src/eyreish/mod.rs index 3559f8b..9094ff1 100644 --- a/src/eyreish/mod.rs +++ b/src/eyreish/mod.rs @@ -53,13 +53,14 @@ pub struct Report { inner: ManuallyDrop>>, } -type ErrorHook = +/// +pub type ErrorHook = Box Box + Sync + Send + 'static>; static HOOK: OnceCell = OnceCell::new(); -/// Error indicating that `set_hook` was unable to install the provided -/// ErrorHook +/// Error indicating that [`set_hook()`] was unable to install the provided +/// [`ErrorHook`]. #[derive(Debug)] pub struct InstallError; @@ -73,7 +74,7 @@ impl StdError for InstallError {} impl Diagnostic for InstallError {} /** -Set the hook? +Set the error hook. */ pub fn set_hook(hook: ErrorHook) -> Result<(), InstallError> { HOOK.set(hook).map_err(|_| InstallError) @@ -145,8 +146,7 @@ pub trait ReportHandler: core::any::Any + Send + Sync { /// /// ```rust /// use indenter::indented; - /// use miette::Diagnostic; - /// use miette::ReportHandler; + /// use miette::{Diagnostic, ReportHandler}; /// /// pub struct Handler; /// @@ -199,7 +199,7 @@ pub trait ReportHandler: core::any::Any + Send + Sync { /// type alias for `Result` /// /// This is a reasonable return type to use throughout your application but also -/// for `fn main`; if you do, failures will be printed along with a backtrace if +/// for `main()`. If you do, failures will be printed along with a backtrace if /// one was captured. /// /// `miette::Result` may be used with one *or* two type parameters. @@ -252,7 +252,7 @@ pub trait ReportHandler: core::any::Any + Send + Sync { /// `miette::Result`. pub type Result = core::result::Result; -/// Provides the `wrap_err` method for `Result`. +/// Provides the [`wrap_err()`](WrapErr::wrap_err) method for [`Result`]. /// /// This trait is sealed and cannot be implemented for types outside of /// `miette`. @@ -261,8 +261,7 @@ pub type Result = core::result::Result; /// /// ``` /// use miette::{WrapErr, IntoDiagnostic, Result}; -/// use std::fs; -/// use std::path::PathBuf; +/// use std::{fs, path::PathBuf}; /// /// pub struct ImportantThing { /// path: PathBuf, @@ -299,13 +298,15 @@ pub type Result = core::result::Result; /// No such file or directory (os error 2) /// ``` /// -/// # Wrapping Types That Don't impl `Error` (e.g. `&str` and `Box`) +/// # Wrapping Types That Do Not Implement `Error` /// -/// Due to restrictions for coherence `Report` cannot impl `From` for types that -/// don't impl `Error`. Attempts to do so will give "this type might implement -/// Error in the future" as an error. As such, `wrap_err`, which uses `From` -/// under the hood, cannot be used to wrap these types. Instead we encourage you -/// to use the combinators provided for `Result` in `std`/`core`. +/// For example `&str` and `Box`. +/// +/// Due to restrictions for coherence `Report` cannot implement `From` for types +/// that don't implement `Error`. Attempts to do so will give `"this type might +/// implement Error in the future"` as an error. As such, `wrap_err()`, which +/// uses `From` under the hood, cannot be used to wrap these types. Instead we +/// encourage you to use the combinators provided for `Result` in `std`/`core`. /// /// For example, instead of this: /// @@ -330,19 +331,19 @@ pub type Result = core::result::Result; /// } /// ``` /// -/// # Effect on downcasting +/// # Effect on Downcasting /// /// After attaching a message of type `D` onto an error of type `E`, the /// resulting `miette::Error` may be downcast to `D` **or** to `E`. /// -/// That is, in codebases that rely on downcasting, miette's wrap_err supports -/// both of the following use cases: +/// That is, in codebases that rely on downcasting, `miette`'s `wrap_err()` +/// supports both of the following use cases: /// /// - **Attaching messages whose type is insignificant onto errors whose type /// is used in downcasts.** /// -/// In other error libraries whose wrap_err is not designed this way, it can -/// be risky to introduce messages to existing code because new message +/// In other error libraries whose `wrap_err()` is not designed this way, it +/// can be risky to introduce messages to existing code because new message /// might break existing working downcasts. In miette, any downcast that /// worked before adding the message will continue to work after you add a /// message, so you should freely wrap errors wherever it would be helpful. @@ -435,13 +436,13 @@ pub trait WrapErr: context::private::Sealed { D: Display + Send + Sync + 'static, F: FnOnce() -> D; - /// Compatibility re-export of wrap_err for interop with `anyhow` + /// Compatibility re-export of `wrap_err()` for interop with `anyhow` #[cfg_attr(track_caller, track_caller)] fn context(self, msg: D) -> Result where D: Display + Send + Sync + 'static; - /// Compatibility re-export of wrap_err_with for interop with `anyhow` + /// Compatibility re-export of `wrap_err_with()` for interop with `anyhow` #[cfg_attr(track_caller, track_caller)] fn with_context(self, f: F) -> Result where @@ -449,7 +450,7 @@ pub trait WrapErr: context::private::Sealed { F: FnOnce() -> D; } -// Not public API. Referenced by macro-generated code. +// Private API. Referenced by macro-generated code. #[doc(hidden)] pub mod private { use super::Report; diff --git a/src/handlers/graphical.rs b/src/handlers/graphical.rs index 3fe2e3c..a30fb04 100644 --- a/src/handlers/graphical.rs +++ b/src/handlers/graphical.rs @@ -14,10 +14,10 @@ other such things. This is the default reporter bundled with `miette`. -This printer can be customized by using `new_themed()` and handing it a +This printer can be customized by using [`new_themed()`](GraphicalReportHandler::new_themed) and handing it a [`GraphicalTheme`] of your own creation (or using one of its own defaults!) -See [`set_hook`](crate::set_hook) for more details on customizing your global +See [`set_hook()`](crate::set_hook) for more details on customizing your global printer. */ #[derive(Debug, Clone)] diff --git a/src/named_source.rs b/src/named_source.rs index 0f89bc1..06c8445 100644 --- a/src/named_source.rs +++ b/src/named_source.rs @@ -1,8 +1,8 @@ use crate::{MietteError, MietteSpanContents, SourceCode, SpanContents}; -/// Utility struct for when you have a regular [`SourceCode`] type, such as a -/// String, that doesn't implement `name`, or if you want to override the -/// `.name()` returned by the `SourceCode`. +/// Utility struct for when you have a regular [`SourceCode`] type that doesn't +/// implement `name`. For example [`String`]. Or if you want to override the +/// `name` returned by the `SourceCode`. pub struct NamedSource { source: Box, name: String,