From 5a0f868c89c31e68238ac2be8af2d824c5b0b748 Mon Sep 17 00:00:00 2001 From: stoutes <31317041+stoutes@users.noreply.github.com> Date: Thu, 22 Jan 2026 20:08:40 -0600 Subject: [PATCH 1/4] docs: Remove #[doc(hidden)] and add documentation for internal traits --- src/data_traits.rs | 21 ++++++------------ src/dimension/dimension_trait.rs | 37 ++++++++++++-------------------- src/dimension/ndindex.rs | 5 +++-- src/layout/mod.rs | 1 - src/slice.rs | 2 -- src/zip/ndproducer.rs | 19 +++++++--------- 6 files changed, 32 insertions(+), 53 deletions(-) diff --git a/src/data_traits.rs b/src/data_traits.rs index a0b33ea12..3627cd93e 100644 --- a/src/data_traits.rs +++ b/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(_: &mut ArrayBase) 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; } @@ -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, NonNull); - - #[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) -> NonNull { 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(self_: ArrayBase) -> Array where @@ -114,13 +112,11 @@ pub unsafe trait Data: RawData /// Converts the array into `Array` if this is possible without /// cloning the array elements. Otherwise, returns `self_` unchanged. - #[doc(hidden)] fn try_into_owned_nocopy(self_: ArrayBase) -> Result, ArrayBase> 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(self_: &ArrayBase) -> ArcArray 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(self_: &mut ArrayBase) 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> + RawDataSubst; - #[doc(hidden)] + /// Creates an owned representation from the given elements. fn new(elements: Vec) -> 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(self_: ArrayBase) -> ArcArray where diff --git a/src/dimension/dimension_trait.rs b/src/dimension/dimension_trait.rs index 3544a7f3c..b848e3828 100644 --- a/src/dimension/dimension_trait.rs +++ b/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 { @@ -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(&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 { 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(d: &D2) -> Option { 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! {} diff --git a/src/dimension/ndindex.rs b/src/dimension/ndindex.rs index ca2a3ea69..61fbb434f 100644 --- a/src/dimension/ndindex.rs +++ b/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: Debug { - #[doc(hidden)] + /// Computes the linear index for this position fn index_checked(&self, dim: &E, strides: &E) -> Option; - #[doc(hidden)] + + /// Computes the linear index for this position without bounds checking. fn index_unchecked(&self, strides: &E) -> isize; } diff --git a/src/layout/mod.rs b/src/layout/mod.rs index 36853848e..d0df87b0b 100644 --- a/src/layout/mod.rs +++ b/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); diff --git a/src/slice.rs b/src/slice.rs index e2ce1e727..063db9fde 100644 --- a/src/slice.rs +++ b/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, out_dim: PhantomData, ) -> SliceInfo @@ -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. diff --git a/src/zip/ndproducer.rs b/src/zip/ndproducer.rs index fe666e81e..b8905c368 100644 --- a/src/zip/ndproducer.rs +++ b/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; - #[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) -> ::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; From 34dd86d09f06aa82a465af2385d5d3034c0f27cc Mon Sep 17 00:00:00 2001 From: stoutes <31317041+stoutes@users.noreply.github.com> Date: Thu, 22 Jan 2026 20:14:16 -0600 Subject: [PATCH 2/4] docs: doc edit --- src/dimension/dimension_trait.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dimension/dimension_trait.rs b/src/dimension/dimension_trait.rs index b848e3828..6d8ec72b6 100644 --- a/src/dimension/dimension_trait.rs +++ b/src/dimension/dimension_trait.rs @@ -178,7 +178,7 @@ pub trait Dimension: /// **Panics** if `Self` has a fixed size that is not `ndim`. fn zeros(ndim: usize) -> Self; - /// Returns the first valid index in the dimension, or `None` if any axis has length 0. + /// Returns the first valid index in the dimension #[inline] fn first_index(&self) -> Option { From eb930dea58b7a35d017a0c057f5b6c772d8a11cd Mon Sep 17 00:00:00 2001 From: stoutes <31317041+stoutes@users.noreply.github.com> Date: Thu, 22 Jan 2026 20:50:12 -0600 Subject: [PATCH 3/4] docs: kept doc(hidden) for data traits (they are internal items) --- src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 41e5ca350..bfd692025 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -186,6 +186,7 @@ mod data_traits; pub use crate::aliases::*; +#[doc(hidden)] pub use crate::data_traits::{Data, DataMut, DataOwned, DataShared, RawData, RawDataClone, RawDataMut, RawDataSubst}; mod free_functions; @@ -221,7 +222,7 @@ mod zip; mod dimension; pub use crate::zip::{FoldWhile, IntoNdProducer, NdProducer, Zip}; - +#[doc(hidden)] pub use crate::layout::Layout; /// Implementation's prelude. Common types used everywhere. From 14ab5545f377f273f6da5ef6fee16777b95bed15 Mon Sep 17 00:00:00 2001 From: stoutes <31317041+stoutes@users.noreply.github.com> Date: Fri, 23 Jan 2026 09:57:06 -0600 Subject: [PATCH 4/4] docs: add safety comments for two unsafe functions. added #allow(missing_docs) for two functions (next_in_dim & next_out_dim) in slice.rs --- src/slice.rs | 4 ++-- src/zip/ndproducer.rs | 15 +++++++++++++-- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/src/slice.rs b/src/slice.rs index 063db9fde..2a882a4d8 100644 --- a/src/slice.rs +++ b/src/slice.rs @@ -676,13 +676,13 @@ pub trait SliceNextDim type InDim: Dimension; /// Number of dimensions that this slicing argument produces in the output array. type OutDim: Dimension; - + #[allow(missing_docs)] fn next_in_dim(&self, _: PhantomData) -> PhantomData<>::Output> where D: Dimension + DimAdd { PhantomData } - + #[allow(missing_docs)] fn next_out_dim(&self, _: PhantomData) -> PhantomData<>::Output> where D: Dimension + DimAdd { diff --git a/src/zip/ndproducer.rs b/src/zip/ndproducer.rs index b8905c368..e6b85e81b 100644 --- a/src/zip/ndproducer.rs +++ b/src/zip/ndproducer.rs @@ -81,9 +81,20 @@ pub trait NdProducer } /// Returns a pointer to the first element of the data. fn as_ptr(&self) -> Self::Ptr; - /// Dereferences the pointer to get a reference to the element. + /// Dereferences the pointer to get a mutable reference to the element. + /// + /// # Safety + /// + /// `ptr` must be a valid pointer obtained from this producer and must point + /// to an initialized element within the data's bounds. Additionally, there + /// must be no other references (mutable or immutable) to this element. unsafe fn as_ref(&self, ptr: Self::Ptr) -> Self::Item; - /// Returns a pointer to the element at the given index without bounds checking. + /// Dereferences the pointer to get a mutable reference to the element. + /// + /// # Safety + /// + /// `ptr` must be a valid, aligned pointer obtained from this producer, pointing + /// to an initialized element within the data's bounds with exclusive access. unsafe fn uget_ptr(&self, i: &Self::Dim) -> Self::Ptr; /// Returns the stride (offset between elements) along the specified axis. fn stride_of(&self, axis: Axis) -> ::Stride;