docs(IntoDiagnostic): Warn of potential data loss (#161)

Fixes: #160

This patch expands on the effects of using IntoDiagnostic and warns
users of potential loss of information when using it on `Diagnostic`
types.

src/eyreish/into_diagnostic.rs

@@ -10,12 +10,19 @@ struct DiagnosticError(Box<dyn std::error::Error + Send + Sync + 'static>);
 impl Diagnostic for DiagnosticError {}
 
 /**
-Convenience trait that adds a `.into_diagnostic()` method that converts a type
-to a `Result<T, Report>`.
+Convenience trait that adds a [`.into_diagnostic()`](IntoDiagnostic::into_diagnostic) method that converts a type implementing
+[`std::error::Error`] to a [`Result<T, Report>`].
+
+## Warning
+
+Calling this on a type implementing [`Diagnostic`] will reduce it to the common denominator of
+[`std::error::Error`]. Meaning all extra information provided by [`Diagnostic`] will be
+inaccessible. If you have a type implementing [`Diagnostic`] consider simply returning it or using
+[`Into`] or the [`Try`](std::ops::Try) operator (`?`).
 */
 pub trait IntoDiagnostic<T, E> {
-    /// Converts [`Result`]-like types that return regular errors into a
-    /// `Result` that returns a [`Diagnostic`].
+    /// Converts [`Result`] types that return regular [`std::error::Error`]s into a
+    /// [`Result`] that returns a [`Diagnostic`].
     fn into_diagnostic(self) -> Result<T, Report>;
 }