SF-Zhou · SF-Zhou · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025 · Copilot
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "massmap"
-version = "0.1.4"
+version = "0.1.5"
 edition = "2024"
 authors = ["SF-Zhou <sfzhou.scut@gmail.com>"]
 homepage = "https://github.com/SF-Zhou/massmap"

diff --git a/src/massmap.rs b/src/massmap.rs
@@ -28,11 +28,11 @@ pub struct MassMapInner<R: MassMapReader, H: MassMapHashLoader = MassMapDefaultH
     /// Metadata describing the layout and hashing strategy of the backing file.
     pub meta: MassMapMeta,
     /// Metadata for each hash bucket in the map.
-    pub(crate) bucket_metas: Vec<MassMapBucketMeta>,
+    pub bucket_metas: Vec<MassMapBucketMeta>,
     /// Hash state initialized with the stored seed.
     build_hasher: H::BuildHasher,
     /// Reader used to access the backing storage.
-    pub(crate) reader: R,
+    pub reader: R,
 }
 
 /// Typed view over a [`MassMapInner`].
@@ -142,24 +142,24 @@ where
     }
 
     /// Exposes a reference to the underlying immutable metadata.
-    /// Exposes a reference to the underlying immutable metadata.
+    /// Returns a reference to the underlying massmap metadata.
+    ///
+    /// The metadata describes the layout, hashing strategy, and configuration
+    /// details of the massmap file. This can be useful for diagnostics,
+    /// testing, or when you need to inspect how the map was constructed.
-    /// Exposes a reference to the underlying immutable metadata.
+    /// Returns a reference to the underlying massmap metadata.
+    ///
+    /// The metadata describes the layout, hashing strategy, and configuration
+    /// details of the massmap file. This can be useful for diagnostics,
+    /// testing, or when you need to inspect how the map was constructed.
-    ///
-    /// This is primarily intended for internal crate use (e.g. merging maps).
-    pub(crate) fn meta(&self) -> &MassMapMeta {
+    pub fn meta(&self) -> &MassMapMeta {
         &self.inner.meta
     }
 
     /// Exposes a reference to the underlying bucket metadata array.
-    /// Exposes a reference to the underlying bucket metadata array.
+    /// Returns a reference to the array of metadata for each hash bucket in the map.
+    ///
+    /// Each [`MassMapBucketMeta`] describes a single bucket's layout in the backing file,
+    /// including its offset, length, and entry count. This information is useful for
+    /// diagnostics, advanced iteration, or direct inspection of the bucket structure.
+    ///
+    /// The returned slice has length equal to the number of buckets in the map
+    /// (see [`bucket_count()`]), with each element corresponding to a bucket in order.
-    /// Exposes a reference to the underlying bucket metadata array.
+    /// Returns a reference to the array of metadata for each hash bucket in the map.
+    ///
+    /// Each [`MassMapBucketMeta`] describes a single bucket's layout in the backing file,
+    /// including its offset, length, and entry count. This information is useful for
+    /// diagnostics, advanced iteration, or direct inspection of the bucket structure.
+    ///
+    /// The returned slice has length equal to the number of buckets in the map
+    /// (see [`bucket_count()`]), with each element corresponding to a bucket in order.
-    pub(crate) fn bucket_metas(&self) -> &[MassMapBucketMeta] {
+    pub fn bucket_metas(&self) -> &[MassMapBucketMeta] {
         &self.inner.bucket_metas
     }
 
-    /// Exposes the underlying header for internal crate use.
-    pub(crate) fn header(&self) -> &MassMapHeader {
+    /// Returns a reference to the underlying massmap header.
+    ///
+    /// This can be used to inspect metadata about the massmap file, such as version or configuration.
-    /// This can be used to inspect metadata about the massmap file, such as version or configuration.
+    /// This provides access to the metadata location information (offset and length) in the massmap file.
-    /// This can be used to inspect metadata about the massmap file, such as version or configuration.
+    /// This provides access to the metadata location information (offset and length) in the massmap file.
+    pub fn header(&self) -> &MassMapHeader {
         &self.inner.header
     }
 
-    /// Exposes a reference to the underlying reader for internal crate use.
-    pub(crate) fn reader(&self) -> &R {
+    /// Returns a reference to the underlying reader used to access the backing storage.
-    /// Returns a reference to the underlying reader used to access the backing storage.
+    /// Returns a reference to the underlying reader used to access the backing storage.
+    ///
+    /// The returned reader provides read-only access to the massmap data and implements
+    /// the [`MassMapReader`](crate::MassMapReader) trait. You can use it to perform
+    /// low-level read operations as defined by the trait. See the [`MassMapReader`]
+    /// documentation for details on available methods and usage.
-    /// Returns a reference to the underlying reader used to access the backing storage.
+    /// Returns a reference to the underlying reader used to access the backing storage.
+    ///
+    /// The returned reader provides read-only access to the massmap data and implements
+    /// the [`MassMapReader`](crate::MassMapReader) trait. You can use it to perform
+    /// low-level read operations as defined by the trait. See the [`MassMapReader`]
+    /// documentation for details on available methods and usage.
+    pub fn reader(&self) -> &R {
         &self.inner.reader
     }
 
@@ -295,7 +295,8 @@ where
             })
     }
 
-    fn bucket_index<Q>(&self, k: &Q) -> usize
+    /// Computes the bucket index for the given key.
-    /// Computes the bucket index for the given key.
+    /// Computes the bucket index for the given key.
+    ///
+    /// # What is a bucket index?
+    /// The bucket index represents the position of the hash bucket in the massmap
+    /// where the given key would be stored. Each bucket contains zero or more key-value pairs.
+    ///
+    /// # Valid range
+    /// Returns a value in the range `0..bucket_count`, where `bucket_count` is the number of buckets
+    /// in the map (i.e., `self.inner.bucket_metas.len()`). The valid range is `0` to `bucket_count - 1`.
+    ///
+    /// # Typical use case
+    /// This method is useful for debugging, testing, or advanced inspection of the map's internal
+    /// structure, such as determining which bucket a key would be assigned to.
-    /// Computes the bucket index for the given key.
+    /// Computes the bucket index for the given key.
+    ///
+    /// # What is a bucket index?
+    /// The bucket index represents the position of the hash bucket in the massmap
+    /// where the given key would be stored. Each bucket contains zero or more key-value pairs.
+    ///
+    /// # Valid range
+    /// Returns a value in the range `0..bucket_count`, where `bucket_count` is the number of buckets
+    /// in the map (i.e., `self.inner.bucket_metas.len()`). The valid range is `0` to `bucket_count - 1`.
+    ///
+    /// # Typical use case
+    /// This method is useful for debugging, testing, or advanced inspection of the map's internal
+    /// structure, such as determining which bucket a key would be assigned to.
+    pub fn bucket_index<Q>(&self, k: &Q) -> usize
     where
         K: Borrow<Q>,
         Q: Eq + Hash + ?Sized,