docs

diff --git a/src/lib.rs b/src/lib.rs
index b343c7d681745e758dea25c37a59c99d69ed64e0..f13d92910ce27b06d7899d206368ec7e1a052a6a 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -73,9 +73,8 @@ use std::ptr::NonNull;
 
 /// **Pointer to manually-memory-managed `T`**
 ///
-/// Ensuring that `Ptr`s are freed at the right time is up to the caller.
-/// But aliasing, and other Rust unsafe footguns,
-/// is (largely) handled by the library.
+/// `Ptr<T>` usually refers to an item on the heap, like `Box<T>`.
+/// It can be made from `T` with [`Ptr::new_heap()`].
 ///
 /// To access the contained data,
 /// [`Ptr::borrow()`]
@@ -90,14 +89,14 @@ use std::ptr::NonNull;
 /// [`.borrow_mut()`](Ptr::borrow_mut()) with
 /// [`MutToken::new_unchecked()`].
 ///
-/// # 
-///
-/// The API is sound in the usual Rust sense:
-/// however, it 
-///
 /// This type is `Copy`.  Copying it (or, indeed, cloning it)
 /// does not copy the underlying data.
 /// Nor is there any reference counting or garbage collection.
+///
+/// Ensuring that `Ptr`s are freed at the right time is up to the caller,
+/// But aliasing, and other Rust unsafe footguns,
+/// is (largely) handled by the library.
+/// See the [module-level documentation](crate).
 pub struct Ptr<T: ?Sized> {
     /// # SAFETY
     ///