docs

diff --git a/src/lib.rs b/src/lib.rs
index 2873b654836a6179a38f23e8ed021c5eef0cca60..3545f9641f3c66a77be44223ac142539f1825bee 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -85,14 +85,14 @@ use std::ptr::NonNull;
 ///
 /// To mutably access the data of more than one node at once,
 /// use
-/// [`IsTokenMut::multi_static`],
+/// [`IsTokenMut::multi_static`]
+/// or
 /// [`IsTokenMut::multi_dynamic`].
-///
 /// To avoid runtime aliasing checks, and take manual control of aliasing,
 /// you can
 /// [`.borrow_mut()`](Ptr::borrow_mut()) with
-/// [`TokenMut::new_unchecked()`].
-/// Or,
+/// [`TokenMut::new_unchecked()`];
+/// or,
 /// `p`[`.as_ptr()`](Ptr::as_ptr)[`.as_ref()`](NonNull::as_ref())
 /// /
 /// `p`[`.as_ptr()`](Ptr::as_ptr)[`.as_mut()`](NonNull::as_mut()).
@@ -442,6 +442,7 @@ impl NoAliasSingleton {
 
 //---------- stack ----------
 
+/// A `Ptr` borrowed from stack data
 pub struct Borrowed<'t, T: ?Sized> {
     ptr: Ptr<T>,
     /// Variance and borrowing:
@@ -469,6 +470,21 @@ impl<'t, T: ?Sized> Borrowed<'t, T> {
     ///
     /// Using `retained` is recommended:
     /// it will ensure that `Ptr`s are still live at that point.
+    ///
+    /// ## Unwinding
+    ///
+    /// Not that `Borrowed` comes with exciting hazards
+    /// in the presence of panics:
+    /// a typical use is to take a stack item,
+    /// link it temporarily into a data structure.
+    ///
+    /// If an unwind occurs before the item is unlinked again,
+    /// the data structure can be corrupted.
+    /// It is the responsibility of the user to avoid this situation.
+    ///
+    /// (Note that use of `Ptr` without `Borrowed` does also come with
+    /// hazards in the face of unwinding,
+    /// but those are typically just memory leaks.)
     pub unsafe fn new(t: &mut T) -> Self {
         Borrowed {
             ptr: Ptr::from_raw(NonNull::from(t)),