From e2ce8c29b431023d6c4c5a45571fa1ebafb18459 Mon Sep 17 00:00:00 2001 From: Lachlan Deakin Date: Tue, 26 Dec 2023 16:31:55 +1100 Subject: [PATCH] Remove `#[doc(hidden)]` from various functions --- CHANGELOG.md | 1 + src/array.rs | 5 ++--- src/array/array_representation.rs | 2 -- src/array/chunk_grid.rs | 7 ------- src/array_subset.rs | 26 -------------------------- src/byte_range.rs | 5 ++--- 6 files changed, 5 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 733480e3..e5e6912b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Improved `Array` documentation - Add store testing utility functions for unified store testing - Make various `Array` methods with `parallel` parameter `pub` + - Remove `#[doc(hidden)]` from various functions which are `unsafe` and primarily intended for internal use ### Fixed - Fixed `MemoryStore::get_partial_values_key` if given an invalid byte range, now returns `InvalidByteRangeError` instead of panicking diff --git a/src/array.rs b/src/array.rs index 6af45044..ec240403 100644 --- a/src/array.rs +++ b/src/array.rs @@ -518,7 +518,8 @@ impl Array { } // Safe transmute, avoiding an allocation where possible -// https://github.com/nabijaczleweli/safe-transmute-rs/issues/16#issuecomment-471066699 +// +// A relevant discussion about this can be found here: https://github.com/nabijaczleweli/safe-transmute-rs/issues/16#issuecomment-471066699 #[doc(hidden)] #[must_use] pub fn safe_transmute_to_bytes_vec(mut from: Vec) -> Vec { @@ -585,7 +586,6 @@ pub fn safe_transmute_to_bytes_vec(mut from: Vec) - } /// Unravel a linearised index to ND indices. -#[doc(hidden)] #[must_use] pub fn unravel_index(mut index: u64, shape: &[u64]) -> ArrayIndices { let len = shape.len(); @@ -601,7 +601,6 @@ pub fn unravel_index(mut index: u64, shape: &[u64]) -> ArrayIndices { } /// Ravel ND indices to a linearised index. -#[doc(hidden)] #[must_use] pub fn ravel_indices(indices: &[u64], shape: &[u64]) -> u64 { let mut index: u64 = 0; diff --git a/src/array/array_representation.rs b/src/array/array_representation.rs index c229cf34..781b6b0b 100644 --- a/src/array/array_representation.rs +++ b/src/array/array_representation.rs @@ -41,9 +41,7 @@ impl ArrayRepresentation { /// Create a new [`ArrayRepresentation`]. /// /// # Safety - /// /// `data_type` and `fill_value` must be compatible. - #[doc(hidden)] #[must_use] pub unsafe fn new_unchecked( array_shape: ArrayShape, diff --git a/src/array/chunk_grid.rs b/src/array/chunk_grid.rs index 1ea0958f..0ee6f561 100644 --- a/src/array/chunk_grid.rs +++ b/src/array/chunk_grid.rs @@ -252,11 +252,9 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync }) } - #[doc(hidden)] /// See [`ChunkGridTraits::grid_shape`]. /// /// # Safety - /// /// The length of `array_shape` must match the dimensionality of the chunk grid. unsafe fn grid_shape_unchecked(&self, array_shape: &[u64]) -> Option; @@ -270,11 +268,9 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync array_shape: &[u64], ) -> Option; - #[doc(hidden)] /// See [`ChunkGridTraits::chunk_shape`]. /// /// # Safety - /// /// The length of `chunk_indices` must match the dimensionality of the chunk grid. unsafe fn chunk_shape_unchecked( &self, @@ -282,7 +278,6 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync array_shape: &[u64], ) -> Option; - #[doc(hidden)] /// See [`ChunkGridTraits::chunk_indices`]. /// /// # Safety @@ -293,7 +288,6 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync array_shape: &[u64], ) -> Option; - #[doc(hidden)] /// See [`ChunkGridTraits::chunk_element_indices`]. /// /// # Safety @@ -304,7 +298,6 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync array_shape: &[u64], ) -> Option; - #[doc(hidden)] /// See [`ChunkGridTraits::subset`]. /// /// # Safety diff --git a/src/array_subset.rs b/src/array_subset.rs index 8400e37b..f3502d8f 100644 --- a/src/array_subset.rs +++ b/src/array_subset.rs @@ -99,9 +99,7 @@ impl ArraySubset { /// Create a new array subset. /// /// # Safety - /// /// The length of `start` and `size` must match. - #[doc(hidden)] #[must_use] pub unsafe fn new_with_start_shape_unchecked(start: ArrayIndices, shape: ArrayShape) -> Self { debug_assert_eq!(start.len(), shape.len()); @@ -127,9 +125,7 @@ impl ArraySubset { /// Create a new array subset from a start and end (inclusive). /// /// # Safety - /// /// The length of `start` and `end` must match. - #[doc(hidden)] #[must_use] pub unsafe fn new_with_start_end_inc_unchecked(start: ArrayIndices, end: ArrayIndices) -> Self { debug_assert_eq!(start.len(), end.len()); @@ -161,9 +157,7 @@ impl ArraySubset { /// Create a new array subset from a start and end (exclusive). /// /// # Safety - /// /// The length of `start` and `end` must match. - #[doc(hidden)] #[must_use] pub unsafe fn new_with_start_end_exc_unchecked(start: ArrayIndices, end: ArrayIndices) -> Self { debug_assert_eq!(start.len(), end.len()); @@ -282,9 +276,7 @@ impl ArraySubset { /// Return the byte ranges of an array subset in an array with `array_shape` and `element_size`. /// /// # Safety - /// /// The length of `array_shape` must match the dimensionality of `array_subset`. - #[doc(hidden)] #[must_use] pub unsafe fn byte_ranges_unchecked( &self, @@ -339,13 +331,10 @@ impl ArraySubset { /// Return the bytes in this array subset from an array with shape `array_shape` and `element_size`. /// /// # Safety - /// /// The length of `array_shape` must match the array subset dimensionality and the array subset must be within the bounds of `array_shape`. /// /// # Panics - /// /// Panics if attempting to reference a byte beyond `usize::MAX`. - #[doc(hidden)] #[must_use] pub unsafe fn extract_bytes_unchecked( &self, @@ -417,13 +406,10 @@ impl ArraySubset { /// Return the elements in this array subset from an array with shape `array_shape`. /// /// # Safety - /// /// The length of `array_shape` must match the array subset dimensionality and the array subset must be within the bounds of `array_shape`. /// /// # Panics - /// /// Panics if attempting to reference a byte beyond `usize::MAX`. - #[doc(hidden)] #[must_use] pub unsafe fn extract_elements_unchecked( &self, @@ -569,9 +555,7 @@ impl ArraySubset { /// Returns an iterator over the indices of elements within the subset. /// /// # Safety - /// /// `array_shape` must match the dimensionality and encapsulate this array subset. - #[doc(hidden)] #[must_use] pub unsafe fn iter_linearised_indices_unchecked<'a>( &'a self, @@ -595,9 +579,7 @@ impl ArraySubset { /// Returns an iterator over the indices of contiguous elements within the subset. /// /// # Safety - /// /// The length of `array_shape` must match the array subset dimensionality. - #[doc(hidden)] #[must_use] pub unsafe fn iter_contiguous_indices_unchecked<'a>( &'a self, @@ -621,9 +603,7 @@ impl ArraySubset { /// Returns an iterator over the linearised indices of contiguous elements within the subset. /// /// # Safety - /// /// The length of `array_shape` must match the array subset dimensionality. - #[doc(hidden)] #[must_use] pub unsafe fn iter_contiguous_linearised_indices_unchecked<'a>( &'a self, @@ -653,9 +633,7 @@ impl ArraySubset { /// Thus, the subsets of the chunks may extend out over the subset. /// /// # Safety - /// /// The length of `chunk_shape` must match the array subset dimensionality. - #[doc(hidden)] #[must_use] pub unsafe fn iter_chunks_unchecked<'a>(&'a self, chunk_shape: &'a [u64]) -> ChunksIterator { ChunksIterator::new_unchecked(self, chunk_shape) @@ -691,9 +669,7 @@ impl ArraySubset { /// The start of the returned array subset is from the start of this array subset. /// /// # Safety - /// /// Panics if the dimensionality of `subset_other` does not match the dimensionality of this array subset. - #[doc(hidden)] #[must_use] pub unsafe fn in_subset_unchecked(&self, subset_other: &Self) -> Self { debug_assert_eq!(subset_other.dimensionality(), self.dimensionality()); @@ -731,9 +707,7 @@ impl ArraySubset { /// Return the overlapping subset between this array subset and `subset_other`. /// /// # Safety - /// /// Panics if the dimensionality of `subset_other` does not match the dimensionality of this array subset. - #[doc(hidden)] #[must_use] pub unsafe fn overlap_unchecked(&self, subset_other: &Self) -> Self { debug_assert_eq!(subset_other.dimensionality(), self.dimensionality()); diff --git a/src/byte_range.rs b/src/byte_range.rs index f91c7ad9..db13027c 100644 --- a/src/byte_range.rs +++ b/src/byte_range.rs @@ -111,7 +111,6 @@ fn validate_byte_ranges(byte_ranges: &[ByteRange], bytes_len: u64) -> bool { /// Extract byte ranges from bytes. /// /// # Errors -/// /// Returns [`InvalidByteRangeError`] if any bytes are requested beyond the end of `bytes`. pub fn extract_byte_ranges( bytes: &[u8], @@ -126,10 +125,10 @@ pub fn extract_byte_ranges( /// Extract byte ranges from bytes. /// /// # Safety -/// /// All byte ranges in `byte_ranges` must specify a range within `bytes`. /// -#[doc(hidden)] +/// # Panics +/// Panics if attempting to reference a byte beyond `usize::MAX`. #[must_use] pub unsafe fn extract_byte_ranges_unchecked( bytes: &[u8],