More doc fixes, made ErrorHook type public.

src/eyreish/mod.rs

@@ -53,13 +53,14 @@ pub struct Report {
     inner: ManuallyDrop<Box<ErrorImpl<()>>>,
 }
 
-type ErrorHook =
+///
+pub type ErrorHook =
     Box<dyn Fn(&(dyn Diagnostic + 'static)) -> Box<dyn ReportHandler> + Sync + Send + 'static>;
 
 static HOOK: OnceCell<ErrorHook> = OnceCell::new();
 
-/// Error indicating that `set_hook` was unable to install the provided
+/// Error indicating that [`set_hook()`] was unable to install the provided
-/// ErrorHook
+/// [`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::{Diagnostic, ReportHandler};
-    /// use miette::ReportHandler;
     ///
     /// pub struct Handler;
     ///
@@ -199,7 +199,7 @@ pub trait ReportHandler: core::any::Any + Send + Sync {
 /// type alias for `Result<T, Report>`
 ///
 /// 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<T, E = Report> = core::result::Result<T, E>;
 
-/// 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<T, E = Report> = core::result::Result<T, E>;
 ///
 /// ```
 /// use miette::{WrapErr, IntoDiagnostic, Result};
-/// use std::fs;
+/// use std::{fs, path::PathBuf};
-/// use std::path::PathBuf;
 ///
 /// pub struct ImportantThing {
 ///     path: PathBuf,
@@ -299,13 +298,15 @@ pub type Result<T, E = Report> = core::result::Result<T, E>;
 ///     No such file or directory (os error 2)
 /// ```
 ///
-/// # Wrapping Types That Don't impl `Error` (e.g. `&str` and `Box<dyn Error>`)
+/// # Wrapping Types That Do Not Implement `Error`
 ///
-/// Due to restrictions for coherence `Report` cannot impl `From` for types that
+/// For example `&str` and `Box<dyn Error>`.
-/// 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`
+/// Due to restrictions for coherence `Report` cannot implement `From` for types
-/// under the hood, cannot be used to wrap these types. Instead we encourage you
+/// that don't implement `Error`. Attempts to do so will give `"this type might
-/// to use the combinators provided for `Result` in `std`/`core`.
+/// 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<T, E = Report> = core::result::Result<T, E>;
 /// }
 /// ```
 ///
-/// # 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
+/// That is, in codebases that rely on downcasting, `miette`'s `wrap_err()`
-/// both of the following use cases:
+/// 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
+///     In other error libraries whose `wrap_err()` is not designed this way, it
-///     be risky to introduce messages to existing code because new message
+/// 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<T, E>: 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<D>(self, msg: D) -> Result<T, Report>
     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<D, F>(self, f: F) -> Result<T, Report>
     where
@@ -449,7 +450,7 @@ pub trait WrapErr<T, E>: 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;

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)]

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
+/// Utility struct for when you have a regular [`SourceCode`] type that doesn't
-/// String, that doesn't implement `name`, or if you want to override the
+/// implement `name`. For example [`String`]. Or if you want to override the
-/// `.name()` returned by the `SourceCode`.
+/// `name` returned by the `SourceCode`.
 pub struct NamedSource {
     source: Box<dyn SourceCode + 'static>,
     name: String,