Document remaining methods

Author: phil-opp

src/volatile_ptr/unstable.rs

@@ -11,10 +11,12 @@ use crate::{
 };
 
 impl<'a, T, A> VolatilePtr<'a, [T], A> {
+    /// Returns the length of the slice.
     pub fn len(self) -> usize {
         self.pointer.len()
     }
 
+    /// Returns whether the slice is empty.
     pub fn is_empty(self) -> bool {
         self.pointer.len() == 0
     }
@@ -239,6 +241,16 @@ impl<'a, T, A> VolatilePtr<'a, [T], A> {
         }
     }
 
+    /// Divides one slice into two at an index.
+    ///
+    /// The first will contain all indices from `[0, mid)` (excluding
+    /// the index `mid` itself) and the second will contain all
+    /// indices from `[mid, len)` (excluding the index `len` itself).
+    ///
+    /// # Panics
+    ///
+    /// Panics if `mid > len`.
+    ///
     pub fn split_at(self, mid: usize) -> (VolatilePtr<'a, [T], A>, VolatilePtr<'a, [T], A>)
     where
         A: Access,
@@ -265,6 +277,13 @@ impl<'a, T, A> VolatilePtr<'a, [T], A> {
         }
     }
 
+    /// Splits the slice into a slice of `N`-element arrays,
+    /// starting at the beginning of the slice,
+    /// and a remainder slice with length strictly less than `N`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `N` is 0.
     pub fn as_chunks<const N: usize>(
         self,
     ) -> (VolatilePtr<'a, [[T; N]], A>, VolatilePtr<'a, [T], A>)
@@ -280,6 +299,14 @@ impl<'a, T, A> VolatilePtr<'a, [T], A> {
         (array_slice, remainder)
     }
 
+    /// Splits the slice into a slice of `N`-element arrays,
+    /// assuming that there's no remainder.
+    ///
+    /// # Safety
+    ///
+    /// This may only be called when
+    /// - The slice splits exactly into `N`-element chunks (aka `self.len() % N == 0`).
+    /// - `N != 0`.
     pub unsafe fn as_chunks_unchecked<const N: usize>(self) -> VolatilePtr<'a, [[T; N]], A>
     where
         A: Access,

src/volatile_ptr/very_unstable.rs

@@ -6,6 +6,14 @@ impl<'a, T, A> VolatilePtr<'a, T, A>
 where
     T: ?Sized,
 {
+    /// Compile-time evaluable variant of [`Self::map`].
+    ///
+    /// This function is a copy of [`Self::map`] that uses unstable compiler functions
+    /// to be callable from `const` contexts.
+    ///
+    /// ## Safety
+    ///
+    /// The safety requirements of [`Self::map`] apply to this method too.
     pub const unsafe fn map_const<F, U>(self, f: F) -> VolatilePtr<'a, U, A>
     where
         F: ~const FnOnce(NonNull<T>) -> NonNull<U>,
@@ -18,6 +26,10 @@ where
 /// Methods for volatile slices
 #[cfg(feature = "unstable")]
 impl<'a, T, A> VolatilePtr<'a, [T], A> {
+    /// Compile-time evaluable variant of [`Self::index`].
+    ///
+    /// This function is a copy of [`Self::index`] that uses unstable compiler functions
+    /// to be callable from `const` contexts.
     pub const fn index_const(self, index: usize) -> VolatilePtr<'a, T, A> {
         assert!(index < self.pointer.len(), "index out of bounds");