From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Thu, 14 Nov 2024 23:50:19 +0000 (+0000)
Subject: docs
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=commitdiff_plain;h=37d9f11560c14299bf9da798e7ee33d2a38bed5e;p=manually-boxed

docs
---

diff --git a/src/lib.rs b/src/lib.rs
index 86e38f5..aa6c9a7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -120,12 +120,32 @@ unsafe impl<T: Sync + ?Sized> Sync for Ptr<T> {}
 unsafe impl<T: Send + ?Sized> Send for Ptr<T> {}
 
 /// Singleton, used for compile-time alias checking
+///
+/// You'll need one owned one of these, from
+/// [`NoAliasSingleton::init()`].
+///
+/// Typically, instead of passing `&mut NoAliasSingleton`
+/// to your own sub-functions,
+/// you'll pass [`MutToken`] (or [`RefToken`],
+/// which can be obtained (and copied)
+/// with
+/// [`IsRefToken::ref_token`]
+/// and
+/// [`IsMutToken::mut_token`].
+///
+/// Those token types are zero-sized types,
+/// so they incur no runtime cost,
+/// even if the compiler can't figure out that
+/// they aren't ever used.
+///
+/// (`NoAliasSingleton` is a ZST too,
+/// but of course `&mut NoAliasSingleton` isn't.)
 #[derive(Debug)] // Not Clone or Copy
 #[non_exhaustive] // unsafe to construct
 pub struct NoAliasSingleton {
 }
 
-/// `&NoAliasSingleton`, but a ZST
+/// `&`[`NoAliasSingleton`], but zero-sized
 ///
 /// We don't actually ever need to look at the data for the singleton.
 /// So the actual pointer is redundant, and, here, absent.
@@ -134,7 +154,7 @@ pub struct RefToken<'a>(
     PhantomData<&'a NoAliasSingleton>,
 );
 
-/// `&mut NoAliasSingleton`, but a ZST
+/// `&mut` [`NoAliasSingleton`], but a zero-sized
 ///
 /// See [`RefToken`]
 #[derive(Debug)]
@@ -143,15 +163,15 @@ pub struct MutToken<'a>(
 );
 
 impl<'a> MutToken<'a> {
-    /// Allowing borrowing on the caller's recognisance
+    /// Allow borrowing on the caller's recognisance
     ///
     /// This will let you call
     /// [`Ptr::borrow()`]/[`borrow_mut()`](Ptr::borrow_mut)
     /// multiple times, retaining and using all the resulting references.
     ///
-    /// SAFETY
+    /// # SAFETY
     ///
-    /// The calls to `borrow` that this enables must not violate
+    /// The calls to `borrow[_mut]` 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,
@@ -432,9 +452,9 @@ impl std::error::Error for BorrowConflict {
 
 type BorrowResult<T> = Result<T, BorrowConflict>;
 
-/// Tracker for multiple borrows
+/// Tracker for multiple borrows (dynamic)
 ///
-/// Returned from `
+/// Returned from [`IsMutToken::multi_dynamic`].
 pub struct MultiDynamic<'a> {
     _tok: MutToken<'a>,
     ref_given: HashSet<NonNull<()>>,
@@ -442,6 +462,9 @@ pub struct MultiDynamic<'a> {
 }
 
 impl<'a> MultiDynamic<'a> {
+    /// Borrow `p` immutably
+    ///
+    /// If `p` has already been mutably borrowed, returns `Err`.
     #[inline]
     pub fn borrow<'r, T>(&mut self, p: Ptr<T>) -> BorrowResult<&'r T>
     where 'a: 'r
@@ -458,6 +481,9 @@ impl<'a> MultiDynamic<'a> {
         Ok(())
     }
 
+    /// Borrow `p` mutably
+    ///
+    /// If `p` has already been borrowed, returns `Err`.
     #[inline]
     pub fn borrow_mut<'r, T>(&mut self, mut p: Ptr<T>)
                              -> BorrowResult<&'r mut T>