Add some docs for BorrowBuf

Signed-off-by: Nick Cameron <nrc@ncameron.org>

Author: nrc

library/std/src/io/readbuf.rs

@@ -7,8 +7,7 @@ use crate::cmp;
 use crate::fmt::{self, Debug, Formatter};
 use crate::mem::MaybeUninit;
 
-// TODO docs
-/// A wrapper around a byte buffer that is incrementally filled and initialized.
+/// A borrowed byte buffer which is incrementally filled and initialized.
 ///
 /// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the
 /// buffer that has been logically filled with data, a region that has been initialized at some point but not yet
@@ -21,9 +20,20 @@ use crate::mem::MaybeUninit;
 /// [ filled |         unfilled         ]
 /// [    initialized    | uninitialized ]
 /// ```
+///
+/// A `BorrowBuf` is created around some existing data (or capacity for data) via a unique reference
+/// (`&mut`). The `BorrowBuf` can be configured (e.g., using `clear` or `set_init`), but otherwise
+/// is read-only. To write into the buffer, use `unfilled` to create a `BorrowCursor`. The cursor
+/// has write-only access to the unfilled portion of the buffer (you can think of it like a
+/// write-only iterator).
+///
+/// The lifetime `'a` is a bound on the lifetime of the underlying data.
 pub struct BorrowBuf<'a> {
+    /// The buffer's underlying data.
     buf: &'a mut [MaybeUninit<u8>],
+    /// The length of `self.buf` which is known to be filled.
     filled: usize,
+    /// The length of `self.buf` which is known to be initialized.
     initialized: usize,
 }
 
@@ -37,7 +47,7 @@ impl Debug for BorrowBuf<'_> {
     }
 }
 
-/// Creates a new `BorrowBuf` from a fully initialized slice.
+/// Create a new `BorrowBuf` from a fully initialized slice.
 impl<'a> From<&'a mut [u8]> for BorrowBuf<'a> {
     #[inline]
     fn from(slice: &'a mut [u8]) -> BorrowBuf<'a> {
@@ -52,7 +62,7 @@ impl<'a> From<&'a mut [u8]> for BorrowBuf<'a> {
     }
 }
 
-/// Creates a new `BorrowBuf` from a fully uninitialized buffer.
+/// Create a new `BorrowBuf` from an uninitialized buffer.
 ///
 /// Use `set_init` if part of the buffer is known to be already initialized.
 impl<'a> From<&'a mut [MaybeUninit<u8>]> for BorrowBuf<'a> {
@@ -90,7 +100,7 @@ impl<'a> BorrowBuf<'a> {
 
     /// Returns a cursor over the unfilled part of the buffer.
     #[inline]
-    pub fn unfilled<'b>(&'b mut self) -> BorrowCursor<'a, 'b> {
+    pub fn unfilled<'this>(&'this mut self) -> BorrowCursor<'this, 'a> {
         BorrowCursor { start: self.filled, buf: self }
     }
 
@@ -118,20 +128,36 @@ impl<'a> BorrowBuf<'a> {
     }
 }
 
-/// A cursor view of a [`BorrowBuf`](BorrowBuf).
+/// A writeable view of the unfilled portion of a [`BorrowBuf`](BorrowBuf).
+///
+/// Provides access to the initialized and uninitialized parts of the underlying `BorrowBuf`.
+/// Data can be written directly to the cursor by using [`append`](BorrowCursor::append) or
+/// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the
+/// indirect case, the caller must call [`advance`](BorrowCursor::advance) after writing to inform
+/// the cursor how many bytes have been written.
 ///
-/// Provides mutable access to the unfilled portion (both initialised and uninitialised data) from
-/// the buffer.
+/// Once data is written to the cursor, it becomes part of the filled portion of the underlying
+/// `BorrowBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks
+/// the unfilled part of the underlying `BorrowBuf`.
+///
+/// The `'buf` lifetime is a bound on the lifetime of the underlying buffer. `'data` is a bound on
+/// that buffer's underlying data.
 #[derive(Debug)]
-pub struct BorrowCursor<'a, 'b> {
-    buf: &'b mut BorrowBuf<'a>,
+pub struct BorrowCursor<'buf, 'data> {
+    /// The underlying buffer.
+    buf: &'buf mut BorrowBuf<'data>,
+    /// The length of the filled portion of the underlying buffer at the time of the cursor's
+    /// creation.
     start: usize,
 }
 
-impl<'a, 'b> BorrowCursor<'a, 'b> {
+impl<'buf, 'data> BorrowCursor<'buf, 'data> {
     /// Clone this cursor.
+    ///
+    /// Since a cursor maintains unique access to its underlying buffer, the cloned cursor is not
+    /// accessible while the clone is alive.
     #[inline]
-    pub fn clone<'c>(&'c mut self) -> BorrowCursor<'a, 'c> {
+    pub fn clone<'this>(&'this mut self) -> BorrowCursor<'this, 'data> {
         BorrowCursor { buf: self.buf, start: self.start }
     }
 
@@ -141,14 +167,16 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
         self.buf.capacity() - self.buf.filled
     }
 
-    /// Returns the number of bytes written to this cursor.
-    // TODO check for reuse uses
+    /// Returns the number of bytes written to this cursor since it was created from a `BorrowBuf`.
+    ///
+    /// Note that if this cursor is a clone of another, then the count returned is the count written
+    /// via either cursor, not the count since the cursor was cloned.
     #[inline]
     pub fn written(&self) -> usize {
         self.buf.filled - self.start
     }
 
-    /// Returns a shared reference to the initialized portion of the buffer.
+    /// Returns a shared reference to the initialized portion of the cursor.
     #[inline]
     pub fn init_ref(&self) -> &[u8] {
         //SAFETY: We only slice the initialized part of the buffer, which is always valid
@@ -157,7 +185,7 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
         }
     }
 
-    /// Returns a mutable reference to the initialized portion of the buffer.
+    /// Returns a mutable reference to the initialized portion of the cursor.
     #[inline]
     pub fn init_mut(&mut self) -> &mut [u8] {
         //SAFETY: We only slice the initialized part of the buffer, which is always valid
@@ -168,25 +196,33 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
         }
     }
 
-    /// Returns a mutable reference to the uninitialized part of the buffer.
+    /// Returns a mutable reference to the uninitialized part of the cursor.
     ///
     /// It is safe to uninitialize any of these bytes.
     #[inline]
     pub fn uninit_mut(&mut self) -> &mut [MaybeUninit<u8>] {
         &mut self.buf.buf[self.buf.initialized..]
     }
 
-    /// A view of the cursor as a mutable slice of `MaybeUninit<u8>`.
+    /// Returns a mutable reference to the whole cursor.
+    ///
+    /// # Safety
+    ///
+    /// The caller must not uninitialize any bytes in the initialized portion of the cursor.
     #[inline]
     pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<u8>] {
         &mut self.buf.buf[self.buf.filled..]
     }
 
-    /// Increases the size of the filled region of the buffer.
+    /// Advance the cursor by asserting that `n` bytes have been filled.
+    ///
+    /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
+    /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
+    /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
     ///
     /// # Safety
     ///
-    /// The caller must ensure that the first `n` elements of the cursor have been properly
+    /// The caller must ensure that the first `n` bytes of the cursor have been properly
     /// initialised.
     #[inline]
     pub unsafe fn advance(&mut self, n: usize) -> &mut Self {
@@ -195,7 +231,7 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
         self
     }
 
-    /// Initialised all bytes in the cursor.
+    /// Initializes all bytes in the cursor.
     #[inline]
     pub fn ensure_init(&mut self) -> &mut Self {
         for byte in self.uninit_mut() {
@@ -208,8 +244,8 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
 
     /// Asserts that the first `n` unfilled bytes of the cursor are initialized.
     ///
-    /// `BorrowBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer
-    /// bytes than are already known to be initialized.
+    /// `BorrowBuf` assumes that bytes are never de-initialized, so this method does nothing when
+    /// called with fewer bytes than are already known to be initialized.
     ///
     /// # Safety
     ///
@@ -220,7 +256,7 @@ impl<'a, 'b> BorrowCursor<'a, 'b> {
         self
     }
 
-    /// Appends data to the cursor, advancing the position within its buffer.
+    /// Appends data to the cursor, advancing position within its buffer.
     ///
     /// # Panics
     ///