Remove #[doc(hidden)] from various functions

LDeakin · Dec 26, 2023 · e2ce8c2 · e2ce8c2
1 parent 6a3618d
commit e2ce8c2
Show file tree

Hide file tree

Showing 6 changed files with 5 additions and 41 deletions.
diff --git 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
@@ -518,7 +518,8 @@ impl<TStorage: ?Sized> Array<TStorage> {
 }
 
 // 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<T: TriviallyTransmutable>(mut from: Vec<T>) -> Vec<u8> {
@@ -585,7 +586,6 @@ pub fn safe_transmute_to_bytes_vec<T: TriviallyTransmutable>(mut from: Vec<T>) -
 }
 
 /// 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
@@ -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
@@ -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<ArrayShape>;
 
@@ -270,19 +268,16 @@ pub trait ChunkGridTraits: dyn_clone::DynClone + core::fmt::Debug + Send + Sync
         array_shape: &[u64],
     ) -> Option<ArrayIndices>;
 
-    #[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,
         chunk_indices: &[u64],
         array_shape: &[u64],
     ) -> Option<ArrayShape>;
 
-    #[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<ArrayIndices>;
 
-    #[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<ArrayIndices>;
 
-    #[doc(hidden)]
     /// See [`ChunkGridTraits::subset`].
     ///
     /// # Safety

diff --git 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<T: std::marker::Copy>(
         &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
@@ -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],