docs

diff --git a/src/lib.rs b/src/lib.rs
index 3545f9641f3c66a77be44223ac142539f1825bee..013a144c92a84a3cb0d17ef49e453cb0e264070b 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -77,6 +77,7 @@ use std::ptr::NonNull;
 /// `Ptr<T>` usually refers to an item on the heap, like `Box<T>`.
 /// It can be made from `T` with [`Ptr::new_heap()`],
 /// or [`From<Box>`](#impl-From%3CBox%3CT%3E%3E-for-Ptr%3CT%3E).
+/// It is then freed again with [`.free_heap()`](Ptr::free_heap).
 ///
 /// To access the contained data use,
 /// [`Ptr::borrow()`]
@@ -357,9 +358,12 @@ impl<T: ?Sized> Ptr<T> {
 
     /// Frees a `Ptr` that was made with `new_heap`
     ///
+    /// The contained `T` is dropped.
+    /// To keep it, use [`.free_heap_return()`](Ptr::free_heap_return).
+    ///
     /// # SAFETY
     ///
-    /// `self` must have come from `new_heap`,
+    /// `self` must have come from `new_heap` (or `From<Box>`)
     /// and be the only remaining copy of this `Ptr`
     /// (or the only one which will be used).
     ///
@@ -376,6 +380,10 @@ impl<T: ?Sized> Ptr<T> {
 
     /// Frees a `Ptr` that was made with `new_heap` and returns the `T`
     ///
+    /// If `T` is not `Sized`,
+    /// you must use [`free_heap`](Ptr::free_heap) (discarding `T`)
+    /// or [`into_box`](Ptr::into_box) (leaving it on the heap).
+    ///
     /// # SAFETY
     ///
     /// The same rules as [`free_heap`](Ptr::free_heap) apply.