Add documentation

src/lib.rs

@@ -60,102 +60,222 @@ impl<const N: usize> Bytes<N> {
         self.bytes.as_ptr()
     }
 
+    /// Returns a raw pointer to the vector’s buffer, which may be mutated through
     pub fn as_mut_ptr(&mut self) -> *mut u8 {
         self.bytes.as_mut_ptr()
     }
 
+    /// Extracts a slice containing the entire buffer.
     pub fn as_slice(&self) -> &[u8] {
         self.bytes.as_slice()
     }
+
+    /// Extracts a mutable slice containing the entire buffer.
     pub fn as_mut_slice(&mut self) -> &mut [u8] {
         self.bytes.as_mut_slice()
     }
 
+    /// Get the capacity of the buffer.
+    ///
+    /// Always equal to the `N` const generic.
     pub const fn capacity(&self) -> usize {
         self.bytes.capacity()
     }
 
+    /// Clear the buffer, making it empty
     pub fn clear(&mut self) {
         self.bytes.clear()
     }
 
-    #[deprecated(note = "Panics when out of capacity")]
+    /// Extends the buffer from an iterator.
+    ///
+    /// # Panic
+    ///
+    /// Panics if the buffer cannot hold all elements of the iterator.
+    #[deprecated(
+        since = "0.4.0",
+        note = "Panics when out of capacity, use try_extend instead"
+    )]
     pub fn extend<I: IntoIterator<Item = u8>>(&mut self, iter: I) {
         self.bytes.extend(iter)
     }
 
+    /// Extends the buffer from an iterator.
+    ///
+    /// Returns [`Err`] if out of capacity
+    pub fn try_extend<I: IntoIterator<Item = u8>>(&mut self, iter: I) -> Result<(), ()> {
+        for b in iter {
+            self.push(b)?;
+        }
+        Ok(())
+    }
+
+    /// Extend the buffer with the contents of a slice
     pub fn extend_from_slice(&mut self, other: &[u8]) -> Result<(), ()> {
         self.bytes.extend_from_slice(other)
     }
 
+    /// Removes the last byte from the buffer and returns it, or `None` if it's empty
     pub fn pop(&mut self) -> Option<u8> {
         self.bytes.pop()
     }
 
+    /// Appends a byte to the back of the collection
     pub fn push(&mut self, byte: u8) -> Result<(), ()> {
         self.bytes.push(byte).map_err(drop)
     }
 
+    /// Removes the last byte from the buffer and returns it
+    ///
+    /// # Safety
+    ///
+    /// This assumes the buffer to have at least one element.
     pub unsafe fn pop_unchecked(&mut self) -> u8 {
         unsafe { self.bytes.pop_unchecked() }
     }
 
+    /// Appends a byte to the back of the buffer
+    ///
+    /// # Safety
+    ///
+    /// This assumes the buffer is not full.
     pub unsafe fn push_unchecked(&mut self, byte: u8) {
         unsafe {
             self.bytes.push_unchecked(byte);
         }
     }
 
+    /// Shortens the buffer, keeping the first `len` elements and dropping the rest.
     pub fn truncate(&mut self, len: usize) {
         self.bytes.truncate(len)
     }
 
+    /// Resizes the buffer in-place so that len is equal to new_len.
+    ///
+    /// If new_len is greater than len, the buffer is extended by the
+    /// difference, with each additional slot filled with `value`. If
+    /// `new_len` is less than `len`, the buffer is simply truncated.
+    ///
+    /// See also [`resize_zero`](Self::resize_zero).
     pub fn resize(&mut self, new_len: usize, value: u8) -> Result<(), ()> {
         self.bytes.resize(new_len, value)
     }
 
+    /// Resizes the buffer in-place so that len is equal to new_len.
+    ///
+    /// If new_len is greater than len, the buffer is extended by the
+    /// difference, with each additional slot filled with `0`. If
+    /// `new_len` is less than `len`, the buffer is simply truncated.
     pub fn resize_zero(&mut self, new_len: usize) -> Result<(), ()> {
         self.bytes.resize_default(new_len)
     }
 
+    /// Forces the length of the buffer to `new_len`.
+    ///
+    /// This is a low-level operation that maintains none of the normal
+    /// invariants of the type. Normally changing the length of a buffer
+    /// is done using one of the safe operations instead, such as
+    /// [`truncate`], [`resize`], [`extend`], or [`clear`].
+    ///
+    /// [`truncate`]: Self::truncate
+    /// [`resize`]: Self::resize
+    /// [`extend`]: core::iter::Extend
+    /// [`clear`]: Self::clear
+    ///
+    /// # Safety
+    ///
+    /// - `new_len` must be less than or equal to [`capacity()`].
+    /// - The elements at `old_len..new_len` must be initialized.
+    ///
+    /// [`capacity()`]: Self::capacity
+    ///
     pub unsafe fn set_len(&mut self, new_len: usize) {
         self.bytes.set_len(new_len)
     }
 
+    /// Removes a byte  from the buffer and returns it.
+    ///
+    /// The removed byte is replaced by the last byte of the vector.
+    ///
+    /// This does not preserve ordering, but is *O*(1).
+    ///
+    /// # Panics
+    ///
+    /// Panics if `index` is out of bounds.
     pub fn swap_remove(&mut self, index: usize) -> u8 {
         self.bytes.swap_remove(index)
     }
 
+    /// Removes a byte  from the buffer and returns it.
+    ///
+    /// The removed byte is replaced by the last byte of the vector.
+    ///
+    /// This does not preserve ordering, but is *O*(1).
+    ///
+    /// # Safety
+    ///
+    /// `index` must not be out of bounds.
     pub unsafe fn swap_remove_unchecked(&mut self, index: usize) -> u8 {
         unsafe { self.bytes.swap_remove_unchecked(index) }
     }
 
+    /// Returns true if the buffer is full
     pub fn is_full(&self) -> bool {
         self.bytes.is_full()
     }
 
+    /// Returns true if the buffer is empty
     pub fn is_empty(&self) -> bool {
         self.bytes.is_empty()
     }
 
+    /// Returns `true` if `needle` is a prefix of the buffer.
+    ///
+    /// Always returns `true` if `needle` is an empty slice.
     pub fn starts_with(&self, needle: &[u8]) -> bool {
         self.bytes.starts_with(needle)
     }
+
+    /// Returns `true` if `needle` is a suffix of the buffer.
+    ///
+    /// Always returns `true` if `needle` is an empty slice.
     pub fn ends_with(&self, needle: &[u8]) -> bool {
         self.bytes.ends_with(needle)
     }
 
+    /// Inserts a byte at position `index` within the buffer, shifting all
+    /// bytes after it to the right.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `index > len`.
     pub fn insert(&mut self, index: usize, value: u8) -> Result<(), ()> {
         self.bytes.insert(index, value).map_err(drop)
     }
 
+    /// Removes and return the byte at position `index` within the buffer, shifting all
+    /// bytes after it to the left.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `index > len`.
     pub fn remove(&mut self, index: usize) -> u8 {
         self.bytes.remove(index)
     }
 
+    /// Retains only the bytes specified by the predicate.
+    ///
+    /// In other words, remove all bytes `b` for which `f(&b)` returns `false`.
+    /// This method operates in place, visiting each element exactly once in the
+    /// original order, and preserves the order of the retained elements.
     pub fn retain(&mut self, f: impl FnMut(&u8) -> bool) {
         self.bytes.retain(f)
     }
+    /// Retains only the bytes specified by the predicate, passing a mutable reference to it.
+    ///
+    /// In other words, remove all bytes `b` for which `f(&mut b)` returns `false`.
+    /// This method operates in place, visiting each element exactly once in the
+    /// original order, and preserves the order of the retained elements.
     pub fn retain_mut(&mut self, f: impl FnMut(&mut u8) -> bool) {
         self.bytes.retain_mut(f)
     }