From 0bad58e80d8ec97654809207c1f22d08ba91bc7f Mon Sep 17 00:00:00 2001
From: tison <wander4096@gmail.com>
Date: Mon, 19 Jan 2026 00:11:50 +0800
Subject: [PATCH] docs: improve docs for Exn methods

Signed-off-by: tison <wander4096@gmail.com>
---
 exn/src/impls.rs | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/exn/src/impls.rs b/exn/src/impls.rs
index 1aa007e..389fe74 100644
--- a/exn/src/impls.rs
+++ b/exn/src/impls.rs
@@ -42,7 +42,13 @@ impl<E: Error + Send + Sync + 'static> Exn<E> {
     /// This will automatically walk the [source chain of the error] and add them as children
     /// frames.
     ///
+    /// See also [`ErrorExt::raise`] for a fluent way to convert an error into an `Exn` instance.
+    ///
+    /// Note that **sources of `error` are degenerated to their string representation** and all type
+    /// information is erased.
+    ///
     /// [source chain of the error]: Error::source
+    /// [`ErrorExt::raise`](crate::ErrorExt)
     #[track_caller]
     pub fn new(error: E) -> Self {
         struct SourceError(String);
@@ -88,24 +94,15 @@ impl<E: Error + Send + Sync + 'static> Exn<E> {
         }
     }
 
-    /// Raise a new exception; this will make the current exception a child of the new one.
-    #[track_caller]
-    pub fn raise<T: Error + Send + Sync + 'static>(self, err: T) -> Exn<T> {
-        let mut new_exn = Exn::new(err);
-        new_exn.frame.children.push(*self.frame);
-        new_exn
-    }
-
-    /// Raise a new exception with multiple children; this will make all given exceptions
-    /// children of the new one.
+    /// Create a new exception with the given error and its children.
     #[track_caller]
-    pub fn raise_all<T, I>(err: E, children: I) -> Self
+    pub fn raise_all<T, I>(error: E, children: I) -> Self
     where
         T: Error + Send + Sync + 'static,
         I: IntoIterator,
         I::Item: Into<Exn<T>>,
     {
-        let mut new_exn = Exn::new(err);
+        let mut new_exn = Exn::new(error);
         for exn in children {
             let exn = exn.into();
             new_exn.frame.children.push(*exn.frame);
@@ -113,6 +110,14 @@ impl<E: Error + Send + Sync + 'static> Exn<E> {
         new_exn
     }
 
+    /// Raise a new exception; this will make the current exception a child of the new one.
+    #[track_caller]
+    pub fn raise<T: Error + Send + Sync + 'static>(self, err: T) -> Exn<T> {
+        let mut new_exn = Exn::new(err);
+        new_exn.frame.children.push(*self.frame);
+        new_exn
+    }
+
     /// Return the current exception.
     pub fn error(&self) -> &E {
         self.frame