From 1934fda9063689885c19180857f13651f7474e7d Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Thu, 14 Nov 2024 22:42:37 +0000
Subject: [PATCH] docs

---
 src/lib.rs | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 7be9207..3dc8d5a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -13,6 +13,10 @@ use std::ptr::NonNull;
 ///
 /// Ensuring that `Ptr`s are freed at the right time is up to the caller.
 /// But aliasing, drop, etc., is (largely) handled by the library.
+///
+/// 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.
 pub struct Ptr<T: ?Sized> {
     /// # SAFETY
     ///
@@ -25,10 +29,15 @@ pub struct Ptr<T: ?Sized> {
     ///   of the `NoAliasSingleton` (possibly via `IsRefToken`
     ///   or `IsMutToken`.
     //
-    // XXXX check variance
+    // Variance: covariant, which is right according to the rules (see
+    // docs for NonNull) since we *do* provide the usual shared XOR
+    // mutable.
     ptr: NonNull<T>,
 }
 
+unsafe impl<T: Sync> Sync for Ptr<T> {}
+unsafe impl<T: Send> Send for Ptr<T> {}
+
 /// Singleton, used for compile-time alias checking
 #[derive(Debug)] // Not Clone or Copy
 #[non_exhaustive] // unsafe to construct
@@ -53,10 +62,20 @@ pub struct MutToken<'a>(
 );
 
 impl<'a> MutToken<'a> {
+    /// Allowing borrowing on the caller's recognisance
     ///
+    /// This will let you call [`Ptr::borrow()`]/[`borrow_kut()`]
+    /// multiple times, retaining and using all the resulting references.
     ///
     /// SAFETY
     ///
+    /// The calls to `borrow` that this enables must not violate
+    /// Rust's rules.  Checking that is up to you.
+    /// 
+    /// So, all of the `Ptr` you `borrow_mut` must be distinct,
+    /// and they must be distinct from your `borrow`s.
+    /// Violating this rule is instant undefined behaviour,
+    /// even if you never read or write the resulting reference(s).
     pub unsafe fn new_unchecked() -> Self { MutToken(PhantomData) }
 }
 
@@ -218,7 +237,7 @@ TODO lifetime is hard
 }
 
 impl NoAliasSingleton {
-    /// Initialise by creating the singleton for alias checking
+    /// Initialise, by creating the singleton for alias checking
     ///
     /// # SAFETY
     ///
-- 
2.30.2