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

---
 src/lib.rs | 49 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index aa6c9a7..2a4bda1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -163,7 +163,7 @@ pub struct MutToken<'a>(
 );
 
 impl<'a> MutToken<'a> {
-    /// Allow borrowing on the caller's recognisance
+    /// Allows borrowing on the caller's recognisance
     ///
     /// This will let you call
     /// [`Ptr::borrow()`]/[`borrow_mut()`](Ptr::borrow_mut)
@@ -188,7 +188,7 @@ impl<'a> MutToken<'a> {
 /// Implemented for `NoAliasSingleton` and the ZST reference tokens,
 /// and `&`-references to them.
 pub unsafe trait IsRefToken<'a>: Sized + Sealed {
-    /// Obtain a new ZST token from something that might be a real object.
+    /// Obtains a new ZST token from something that might be a real object.
     #[inline]
     fn ref_token(self) -> RefToken<'a> {
         RefToken(PhantomData)
@@ -200,13 +200,13 @@ pub unsafe trait IsRefToken<'a>: Sized + Sealed {
 /// Implemented for `NoAliasSingleton` and `MutToken`,
 /// and `&mut`-references to them.
 pub unsafe trait IsMutToken<'a>: IsRefToken<'a> + Sized + Sealed {
-    /// Obtain a new ZST token from something that might be a real object.
+    /// Obtains a new ZST token from something that might be a real object.
     #[inline]
     fn mut_token<'r>(self) -> MutToken<'r> where 'a: 'r {
         MutToken(PhantomData)
     }
 
-    /// Borrow from a small, fixed, number of multiple `Ptr`
+    /// Borrows from a small, fixed, number of multiple `Ptr`
     ///
     /// Call
     /// [`.borrow`](MultiStatic::borrow)
@@ -225,7 +225,7 @@ pub unsafe trait IsMutToken<'a>: IsRefToken<'a> + Sized + Sealed {
         }
     }
 
-    /// Borrow from an unknown number of `Ptr` with dynamic runtime checking
+    /// Borrows from an unknown number of `Ptr` with dynamic runtime checking
     ///
     /// Call
     /// [`.borrow`](MultiDynamic::borrow)
@@ -281,7 +281,7 @@ impl<T: ?Sized> Ptr<T> {
         Box::new(t).into()
     }
 
-    /// Borrow the contained data, immutably
+    /// Borrows the contained data, immutably
     #[inline]
     pub fn borrow<'a>(self, tok: impl IsRefToken<'a>) -> &'a T {
         let _ = tok;
@@ -295,7 +295,7 @@ impl<T: ?Sized> Ptr<T> {
         }
     }
 
-    /// Borrow the contained data, mutably
+    /// Borrows the contained data, mutably
     #[inline]
     pub fn borrow_mut<'a>(mut self, tok: impl IsMutToken<'a>) -> &'a mut T {
         let _ = tok;
@@ -309,7 +309,7 @@ impl<T: ?Sized> Ptr<T> {
         }
     }
 
-    /// Return the raw data pointer
+    /// Returns the raw data pointer
     ///
     /// Useful if you want to compare pointers, or something.
     ///
@@ -388,7 +388,7 @@ TODO lifetime is hard
 }
 
 impl NoAliasSingleton {
-    /// Initialise, by creating the singleton for alias checking
+    /// Initialises, by creating the singleton for alias checking
     ///
     /// # SAFETY
     ///
@@ -421,7 +421,9 @@ impl<T: ?Sized> From<Box<T>> for Ptr<T> {
     }
 }
 
+/// Convenience trait for working with `Option<Ptr<_>>`
 pub trait OptionPtrExt<T: ?Sized> {
+    /// Returns the pointer, which will be null iff `self` is `None`
     fn as_ptr(self) -> Option<*mut T>;
 }
 impl<T: ?Sized> OptionPtrExt<T> for Option<Ptr<T>> {
@@ -447,8 +449,7 @@ impl Display for BorrowConflict {
         write!(f, "conflicting borrows attempted")
     }
 }
-impl std::error::Error for BorrowConflict {
-}
+impl std::error::Error for BorrowConflict {}
 
 type BorrowResult<T> = Result<T, BorrowConflict>;
 
@@ -506,6 +507,9 @@ impl<'a> MultiDynamic<'a> {
 
 //---------- multi-borrowing ----------
 
+/// Tracker for multiple borrows (static)
+///
+/// Returned from [`IsMutToken::multi_static`].
 pub struct MultiStatic<'a, L> {
     tok: MutToken<'a>,
     l: L,
@@ -516,10 +520,15 @@ fn forbid_alias(this: *const (), new: NonNull<()>) -> BorrowResult<()> {
     Ok(())
 }
 
-pub unsafe trait MultiStaticList {
-    fn alias_check_ref(&self, p: NonNull<()>) -> BorrowResult<()>;
-    fn alias_check_mut(&self, p: NonNull<()>) -> BorrowResult<()>;
+mod multi_static {
+    use super::*;
+    pub unsafe trait MultiStaticList {
+        fn alias_check_ref(&self, p: NonNull<()>) -> BorrowResult<()>;
+        fn alias_check_mut(&self, p: NonNull<()>) -> BorrowResult<()>;
+    }
 }
+use multi_static::MultiStaticList;
+
 unsafe impl MultiStaticList for () {
     fn alias_check_ref(&self, _: NonNull<()>) -> BorrowResult<()> {
         Ok(())
@@ -549,6 +558,12 @@ unsafe impl<L: MultiStaticList> MultiStaticList for (L, NonNull<()>) {
 }
 
 impl<'a, L: MultiStaticList> MultiStatic<'a, L> {
+    /// Borrows `p` immutably
+    ///
+    /// Returns the requested borrow, `&T`,
+    /// and `MultiStatic` that can be used for further borrowing.
+    ///
+    /// If `p` has already been mutably borrowed, returns `Err`.
     pub fn borrow<'r, T>(self, p: Ptr<T>) -> Result<
         (&'r T, MultiStatic<'a, (L, *const ())>),
         Self
@@ -567,6 +582,12 @@ impl<'a, L: MultiStaticList> MultiStatic<'a, L> {
         }
     }
 
+    /// Borrows `p` mutably
+    ///
+    /// Returns the requested borrow, `&mut T`,
+    /// and `MultiStatic` that can be used for further borrowing.
+    ///
+    /// If `p` has already been borrowed, returns `Err`.
     pub fn borrow_mut<'r, T>(self, mut p: Ptr<T>) -> Result<
         (&'r mut T, MultiStatic<'a, (L, NonNull<()>)>),
         Self
-- 
2.30.2