docs: Remove #[doc(hidden)] and add documentation for internal traits

Author: stoutes

src/data_traits.rs

@@ -39,8 +39,10 @@ pub unsafe trait RawData: Sized
 {
     /// The array element type.
     type Elem;
-
-    #[doc(hidden)]
+    /// Returns whether `self_ptr` points within this data's memory bounds.
+    ///
+    /// Valid range includes all element positions plus one-past-the-end.
+    /// Used for internal bounds checking in unsafe operations.
     fn _is_pointer_inbounds(&self, ptr: *const Self::Elem) -> bool;
 
     private_decl! {}
@@ -61,7 +63,6 @@ pub unsafe trait RawDataMut: RawData
     ///
     /// Additionally, if `Self` provides safe mutable access to array elements,
     /// then this method **must** panic or ensure that the data is unique.
-    #[doc(hidden)]
     fn try_ensure_unique<D>(_: &mut ArrayBase<Self, D>)
     where
         Self: Sized,
@@ -71,7 +72,6 @@ pub unsafe trait RawDataMut: RawData
     ///
     /// If `Self` provides safe mutable access to array elements, then it
     /// **must** return `Some(_)`.
-    #[doc(hidden)]
     fn try_is_unique(&mut self) -> Option<bool>;
 }
 
@@ -83,11 +83,10 @@ pub unsafe trait RawDataMut: RawData
 #[allow(clippy::missing_safety_doc)] // not implementable downstream
 pub unsafe trait RawDataClone: RawData
 {
-    #[doc(hidden)]
     /// Unsafe because, `ptr` must point inside the current storage.
     unsafe fn clone_with_ptr(&self, ptr: NonNull<Self::Elem>) -> (Self, NonNull<Self::Elem>);
-
-    #[doc(hidden)]
+    /// Clones data from `other` into `self`, adjusting the pointer accordingly. `ptr` must point 
+    /// inside `other`'s storage.
     unsafe fn clone_from_with_ptr(&mut self, other: &Self, ptr: NonNull<Self::Elem>) -> NonNull<Self::Elem>
     {
         let (data, ptr) = other.clone_with_ptr(ptr);
@@ -105,7 +104,6 @@ pub unsafe trait RawDataClone: RawData
 pub unsafe trait Data: RawData
 {
     /// Converts the array to a uniquely owned array, cloning elements if necessary.
-    #[doc(hidden)]
     #[allow(clippy::wrong_self_convention)]
     fn into_owned<D>(self_: ArrayBase<Self, D>) -> Array<Self::Elem, D>
     where
@@ -114,13 +112,11 @@ pub unsafe trait Data: RawData
 
     /// Converts the array into `Array<A, D>` if this is possible without
     /// cloning the array elements. Otherwise, returns `self_` unchanged.
-    #[doc(hidden)]
     fn try_into_owned_nocopy<D>(self_: ArrayBase<Self, D>) -> Result<Array<Self::Elem, D>, ArrayBase<Self, D>>
     where D: Dimension;
 
     /// Return a shared ownership (copy on write) array based on the existing one,
     /// cloning elements if necessary.
-    #[doc(hidden)]
     #[allow(clippy::wrong_self_convention)]
     fn to_shared<D>(self_: &ArrayBase<Self, D>) -> ArcArray<Self::Elem, D>
     where
@@ -148,7 +144,6 @@ pub unsafe trait Data: RawData
 pub unsafe trait DataMut: Data + RawDataMut
 {
     /// Ensures that the array has unique access to its data.
-    #[doc(hidden)]
     #[inline]
     fn ensure_unique<D>(self_: &mut ArrayBase<Self, D>)
     where
@@ -159,7 +154,6 @@ pub unsafe trait DataMut: Data + RawDataMut
     }
 
     /// Returns whether the array has unique access to its data.
-    #[doc(hidden)]
     #[inline]
     #[allow(clippy::wrong_self_convention)] // mut needed for Arc types
     fn is_unique(&mut self) -> bool
@@ -514,12 +508,11 @@ pub unsafe trait DataOwned: Data
 {
     /// Corresponding owned data with MaybeUninit elements
     type MaybeUninit: DataOwned<Elem = MaybeUninit<Self::Elem>> + RawDataSubst<Self::Elem, Output = Self>;
-    #[doc(hidden)]
+    /// Creates an owned representation from the given elements.
     fn new(elements: Vec<Self::Elem>) -> Self;
 
     /// Converts the data representation to a shared (copy on write)
     /// representation, cloning the array elements if necessary.
-    #[doc(hidden)]
     #[allow(clippy::wrong_self_convention)]
     fn into_shared<D>(self_: ArrayBase<Self, D>) -> ArcArray<Self::Elem, D>
     where

src/dimension/dimension_trait.rs

@@ -96,10 +96,10 @@ pub trait Dimension:
             .try_fold(1_usize, |s, &a| s.checked_mul(a))
     }
 
-    #[doc(hidden)]
+    /// Returns the dimension as a slice of axis lengths.
     fn slice(&self) -> &[Ix];
-
-    #[doc(hidden)]
+    
+    /// Returns the dimension as a mutable slice of axis lengths.
     fn slice_mut(&mut self) -> &mut [Ix];
 
     /// Borrow as a read-only array view.
@@ -114,7 +114,7 @@ pub trait Dimension:
         ArrayViewMut1::from(self.slice_mut())
     }
 
-    #[doc(hidden)]
+    /// Returns `true` if the dimensions have equal axis lengths.
     fn equal(&self, rhs: &Self) -> bool
     {
         self.slice() == rhs.slice()
@@ -124,7 +124,6 @@ pub trait Dimension:
     ///
     /// If the array is non-empty, the strides result in contiguous layout; if
     /// the array is empty, the strides are all zeros.
-    #[doc(hidden)]
     fn default_strides(&self) -> Self
     {
         // Compute default array strides
@@ -150,7 +149,6 @@ pub trait Dimension:
     ///
     /// If the array is non-empty, the strides result in contiguous layout; if
     /// the array is empty, the strides are all zeros.
-    #[doc(hidden)]
     fn fortran_strides(&self) -> Self
     {
         // Compute fortran array strides
@@ -180,7 +178,7 @@ pub trait Dimension:
     /// **Panics** if `Self` has a fixed size that is not `ndim`.
     fn zeros(ndim: usize) -> Self;
 
-    #[doc(hidden)]
+    /// Returns the first valid index in the dimension, or `None` if any axis has length 0.
     #[inline]
     fn first_index(&self) -> Option<Self>
     {
@@ -192,7 +190,6 @@ pub trait Dimension:
         Some(Self::zeros(self.ndim()))
     }
 
-    #[doc(hidden)]
     /// Iteration -- Use self as size, and return next index after `index`
     /// or None if there are no more.
     // FIXME: use &Self for index or even &mut?
@@ -217,7 +214,6 @@ pub trait Dimension:
         }
     }
 
-    #[doc(hidden)]
     /// Iteration -- Use self as size, and create the next index after `index`
     /// Return false if iteration is done
     ///
@@ -245,7 +241,6 @@ pub trait Dimension:
     /// strides are equal.
     ///
     /// Note: Returns `false` if any of the ndims don't match.
-    #[doc(hidden)]
     fn strides_equivalent<D>(&self, strides1: &Self, strides2: &D) -> bool
     where D: Dimension
     {
@@ -256,7 +251,6 @@ pub trait Dimension:
                 .all(|(&d, &s1, &s2)| d <= 1 || s1 as isize == s2 as isize)
     }
 
-    #[doc(hidden)]
     /// Return stride offset for index.
     fn stride_offset(index: &Self, strides: &Self) -> isize
     {
@@ -267,14 +261,13 @@ pub trait Dimension:
         offset
     }
 
-    #[doc(hidden)]
     /// Return stride offset for this dimension and index.
     fn stride_offset_checked(&self, strides: &Self, index: &Self) -> Option<isize>
     {
         stride_offset_checked(self.slice(), strides.slice(), index.slice())
     }
 
-    #[doc(hidden)]
+    /// Returns the size of the last dimension axis, or 0 for scalar (zero-dimensional) arrays.
     fn last_elem(&self) -> usize
     {
         if self.ndim() == 0 {
@@ -283,15 +276,16 @@ pub trait Dimension:
             self.slice()[self.ndim() - 1]
         }
     }
-
-    #[doc(hidden)]
+    /// Sets the length of the last axis to `i`.
     fn set_last_elem(&mut self, i: usize)
     {
         let nd = self.ndim();
         self.slice_mut()[nd - 1] = i;
     }
 
-    #[doc(hidden)]
+    /// Returns `true` if the dimension and strides represent contiguous memory layout.
+    ///
+    /// Handles both standard (C-order) and reversed (negative stride) contiguous layouts.
     fn is_contiguous(dim: &Self, strides: &Self) -> bool
     {
         let defaults = dim.default_strides();
@@ -324,7 +318,6 @@ pub trait Dimension:
     /// (in ascending order).
     ///
     /// Assumes that no stride value appears twice.
-    #[doc(hidden)]
     fn _fastest_varying_stride_order(&self) -> Self
     {
         let mut indices = self.clone();
@@ -340,7 +333,6 @@ pub trait Dimension:
 
     /// Compute the minimum stride axis (absolute value), under the constraint
     /// that the length of the axis is > 1;
-    #[doc(hidden)]
     fn min_stride_axis(&self, strides: &Self) -> Axis
     {
         let n = match self.ndim() {
@@ -356,7 +348,6 @@ pub trait Dimension:
 
     /// Compute the maximum stride axis (absolute value), under the constraint
     /// that the length of the axis is > 1;
-    #[doc(hidden)]
     fn max_stride_axis(&self, strides: &Self) -> Axis
     {
         match self.ndim() {
@@ -376,7 +367,7 @@ pub trait Dimension:
         IxDyn(self.slice())
     }
 
-    #[doc(hidden)]
+    /// Converts from another dimension type, returning `None` if `ndim` differs.
     fn from_dimension<D2: Dimension>(d: &D2) -> Option<Self>
     {
         let mut s = Self::default();
@@ -389,11 +380,11 @@ pub trait Dimension:
             None
         }
     }
-
-    #[doc(hidden)]
+    
+    /// Inserts a new axis of length 1 at the given position, increasing dimensionality.
     fn insert_axis(&self, axis: Axis) -> Self::Larger;
 
-    #[doc(hidden)]
+    /// Removes the specified axis, decreasing dimensionality. Panics if axis is invalid.
     fn try_remove_axis(&self, axis: Axis) -> Self::Smaller;
 
     private_decl! {}

src/dimension/ndindex.rs

@@ -19,9 +19,10 @@ use crate::{Dim, Dimension, IntoDimension, Ix, Ix0, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6
 #[allow(clippy::missing_safety_doc)] // TODO: Add doc
 pub unsafe trait NdIndex<E>: Debug
 {
-    #[doc(hidden)]
+    /// Computes the linear index for this position
     fn index_checked(&self, dim: &E, strides: &E) -> Option<isize>;
-    #[doc(hidden)]
+
+    /// Computes the linear index for this position without bounds checking.
     fn index_unchecked(&self, strides: &E) -> isize;
 }
 

src/layout/mod.rs

@@ -3,7 +3,6 @@ mod layoutfmt;
 // Layout is a bitset used for internal layout description of
 // arrays, producers and sets of producers.
 // The type is public but users don't interact with it.
-#[doc(hidden)]
 /// Memory layout description
 #[derive(Copy, Clone)]
 pub struct Layout(u32);

src/slice.rs

@@ -484,7 +484,6 @@ where
     /// The caller must ensure that `in_dim` and `out_dim` are consistent with
     /// `indices` and that `indices.as_ref()` always returns the same value
     /// when called multiple times.
-    #[doc(hidden)]
     pub unsafe fn new_unchecked(
         indices: T, in_dim: PhantomData<Din>, out_dim: PhantomData<Dout>,
     ) -> SliceInfo<T, Din, Dout>
@@ -671,7 +670,6 @@ where
 }
 
 /// Trait for determining dimensionality of input and output for [`s!`] macro.
-#[doc(hidden)]
 pub trait SliceNextDim
 {
     /// Number of dimensions that this slicing argument consumes in the input array.

src/zip/ndproducer.rs

@@ -66,33 +66,30 @@ pub trait NdProducer
     // current element. It doesn't have to be a pointer (see Indices).
     // Its main function is that it can be incremented with a particular
     // stride (= along a particular axis)
-    #[doc(hidden)]
     /// Pointer or stand-in for pointer
     type Ptr: Offset<Stride = Self::Stride>;
-    #[doc(hidden)]
     /// Pointer stride
     type Stride: Copy;
-
-    #[doc(hidden)]
+    /// Returns the memory layout of this data representation.
     fn layout(&self) -> Layout;
     /// Return the shape of the producer.
     fn raw_dim(&self) -> Self::Dim;
-    #[doc(hidden)]
+    /// Returns `true` if this producer's dimension matches the given dimension.
     fn equal_dim(&self, dim: &Self::Dim) -> bool
     {
         self.raw_dim() == *dim
     }
-    #[doc(hidden)]
+    /// Returns a pointer to the first element of the data.
     fn as_ptr(&self) -> Self::Ptr;
-    #[doc(hidden)]
+    /// Dereferences the pointer to get a reference to the element.
     unsafe fn as_ref(&self, ptr: Self::Ptr) -> Self::Item;
-    #[doc(hidden)]
+    /// Returns a pointer to the element at the given index without bounds checking.
     unsafe fn uget_ptr(&self, i: &Self::Dim) -> Self::Ptr;
-    #[doc(hidden)]
+    /// Returns the stride (offset between elements) along the specified axis.
     fn stride_of(&self, axis: Axis) -> <Self::Ptr as Offset>::Stride;
-    #[doc(hidden)]
+    /// Returns the stride of the fastest-varying (most contiguous) dimension.
     fn contiguous_stride(&self) -> Self::Stride;
-    #[doc(hidden)]
+    /// Splits each component of this producer tuple along the specified axis at the given index.
     fn split_at(self, axis: Axis, index: usize) -> (Self, Self)
     where Self: Sized;