From f615eb9cb0a50f13f6a8e26cd915066b5c815adc Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Thu, 14 Nov 2024 23:36:59 +0000
Subject: [PATCH] docs

---
 src/lib.rs       | 14 ++++++++++++--
 src/test.rs      |  3 ++-
 src/test/demo.rs |  2 +-
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index a859008..8124c38 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -74,7 +74,8 @@ use std::ptr::NonNull;
 /// **Pointer to manually-memory-managed `T`**
 ///
 /// `Ptr<T>` usually refers to an item on the heap, like `Box<T>`.
-/// It can be made from `T` with [`Ptr::new_heap()`].
+/// It can be made from `T` with [`Ptr::new_heap()`],
+/// or [`From<Box>`](#impl-From%3CBox%3CT%3E%3E-for-Ptr%3CT%3E).
 ///
 /// To access the contained data,
 /// [`Ptr::borrow()`]
@@ -253,12 +254,14 @@ impl<T: ?Sized> Clone for Ptr<T> { fn clone(&self) -> Self { *self } }
 impl<T: ?Sized> Copy for Ptr<T> {}
 
 impl<T: ?Sized> Ptr<T> {
+    /// Makes a new `Ptr`, moving the `T` to a new heap allocation
     pub fn new_heap(t: T) -> Self
     where T: Sized
     {
         Box::new(t).into()
     }
 
+    /// Borrow the contained data, immutably
     #[inline]
     pub fn borrow<'a>(self, tok: impl IsRefToken<'a>) -> &'a T {
         let _ = tok;
@@ -272,6 +275,7 @@ impl<T: ?Sized> Ptr<T> {
         }
     }
 
+    /// Borrow the contained data, mutably
     #[inline]
     pub fn borrow_mut<'a>(mut self, tok: impl IsMutToken<'a>) -> &'a mut T {
         let _ = tok;
@@ -285,7 +289,13 @@ impl<T: ?Sized> Ptr<T> {
         }
     }
 
-    /// Useful if you want to compare pointers, or something
+    /// Return the raw data pointer
+    ///
+    /// Useful if you want to compare pointers, or something.
+    ///
+    /// If `Ptr` was made with `new_heap` or `From<Box<_>>`,
+    /// this pointer has the same properties as `Box`'s.
+    /// But of course many copies may exist.
     pub fn as_ptr(self) -> NonNull<T> {
         self.ptr
     }
diff --git a/src/test.rs b/src/test.rs
index 996db00..ba415f0 100644
--- a/src/test.rs
+++ b/src/test.rs
@@ -45,7 +45,8 @@ fn demo() {
 #[test]
 fn unsize() {
     let mut noalias = unsafe { NoAliasSingleton::init() };
-    let p = Ptr::new_heap("hi");
+    let b: Box<str> = "hi".into();
+    let p: Ptr<str> = Ptr::from(b);
     println!("{}", p.borrow(&noalias));
     unsafe { p.free_heap(&mut noalias) };
 }
diff --git a/src/test/demo.rs b/src/test/demo.rs
index b4536b5..7d9cff3 100644
--- a/src/test/demo.rs
+++ b/src/test/demo.rs
@@ -139,7 +139,7 @@ impl<T: Debug> List<T> {
         } else {
             *tail = None;
         }
-        let deleted = unsafe { deleting.free_heap(&mut tok) };
+        let deleted = unsafe { deleting.from_heap(&mut tok) };
         Some(deleted.data)
     }
 
-- 
2.30.2