Refactor the documentation

README.md

@@ -8,7 +8,7 @@ supporting multiple concurrent reads and exclusively allowing one write operatio
 
 - **Cursors:** Provide cursors for precise and efficient iteration over the array. Cursors have both immutable and mutable versions. One can hold multiple immutable cursors or hold a mutable cursor exclusively at a time. 
 - **Marking:** Provide ability to mark entries and the XArray itself for easy state tracking.
-- **Generics:** Generic implementation that can work with any entry type and any inner locks that fits the use case.
+- **Generics:** Generic implementation that can work with any entry type that fits the use case.
 - **Copy-on-Write (COW):** Efficient cloning of XArrays with shared structure until mutation.
 
 ## Installation
@@ -68,34 +68,6 @@ for i in 0..10000 {
 }
 ```
 
-### Specify inner Locks
-Here is an example of declaring a SpinLock in your own project library as an inner lock for an xarray:
-```rust
-    use crate::{SpinLock, SpinLockGuard};
-
-    impl<T> MutexLock<T> for SpinLock<T> {
-        type Target<'a> = SpinLockGuard<'a, T>
-        where T: 'a;
-
-        fn new(inner: T) -> Self {
-            SpinLock::new(inner)
-        }
-
-        fn lock(&self) -> Self::Target<'_> {
-            self.lock().unwrap()
-        }
-    }
-
-    abstract_lock_to!(SpinLock, MySpinLock);
-
-    let mut xarray_arc: XArray<Arc<i32>, MySpinLock> = XArray::new();
-    
-```
-
-- Here `MySpinLock` is a HKT(Higher-Kind Type) abstraction for `crate::SpinLock`. 
-- The real lock type that be abstracted should implement `MutexLock` trait. 
-- This crate has abstracted `std::sync::Mutex` to `StdMutex` and set it as the default inner lock for std users.
-
 ### Using Marks
 
 Here is an example of using marks for the stored pages in the XArray, where PageMark represents the states of each individual Page:

src/borrow.rs

@@ -1,13 +1,21 @@
 use core::{marker::PhantomData, ptr::NonNull};
 
+/// This represents a dormant mutable reference that can be awakened when the original reference
+/// and all its derived references are dead.
+///
+/// See also
+/// <https://github.com/rust-lang/rust/blob/35dfc67d94c47a6c6ae28c46e7dc1c547f772485/library/alloc/src/collections/btree/borrow.rs#L14>.
 pub(super) struct DormantMutRef<'a, T> {
     ptr: NonNull<T>,
     _marker: PhantomData<&'a mut T>,
 }
 
 impl<'a, T> DormantMutRef<'a, T> {
+    /// Creates a dormant mutable reference and returns both the original reference and the dormant
+    /// reference, so that the original reference can continue to be used.
     pub fn new(val: &'a mut T) -> (&'a mut T, DormantMutRef<'a, T>) {
         let mut ptr = NonNull::from(val);
+        // SAFETY: The original reference is still exclusive and can continue to be used.
         let new_val = unsafe { ptr.as_mut() };
         (
             new_val,
@@ -18,11 +26,29 @@ impl<'a, T> DormantMutRef<'a, T> {
         )
     }
 
+    /// Awakens the dormant references after the original reference and all its derived references
+    /// are dead.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the original reference and all its derived references
+    /// (including derived dormant references) are now dead.
     pub unsafe fn awaken(mut self) -> &'a mut T {
+        // SAFETY: The safety requirements of the method ensure that the reference is valid and
+        // exclusive.
         unsafe { self.ptr.as_mut() }
     }
 
+    /// Reborrows the dormant references after the original reference and all derived references
+    /// are dead.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the original reference and all its derived references
+    /// (including derived dormant references) are now dead.
     pub unsafe fn reborrow(&mut self) -> &'a mut T {
+        // SAFETY: The safety requirements of the method ensure that the reference is valid and
+        // exclusive.
         unsafe { self.ptr.as_mut() }
     }
 }

src/cursor.rs

@@ -16,10 +16,26 @@ struct ReadWrite {}
 impl Operation for ReadOnly {}
 impl Operation for ReadWrite {}
 
-/// CursorState represents the current state of the cursor. Currently, there are two possible states:
-/// 1. inactive: the state where the cursor is not positioned on any node.
-/// 2. positioned on a node: this state includes information about the node the cursor is on,
-/// as well as the offset of the entry that needs to be operated on within the slots of the current node.
+/// A type representing the state of a [`Cursor`] or a [`CursorMut`]. Currently, there are three
+/// possible states:
+///  - `Inactive`: The cursor is not positioned on any node.
+///  - `AtNode`: The cursor is positioned on some node and holds a shared reference to it.
+///  - `AtNodeMut`: The cursor is positioned on some node and holds an exclusive reference to it.
+///
+/// Currently, a cursor never ends up on an interior node. In other words, when methods of `Cursor`
+/// or `CursorMut` finish, the cursor will either not positioned on any node or positioned on some
+/// leaf node.
+///
+/// A `Cursor` manages its state with `CursorState<'a, I, ReadOnly>`, which will never be in the
+/// `AtNodeMut` state. A `Cursor` never attempts to perform modification, so it never holds an
+/// exclusive reference.
+///
+/// On contrast, a `CursorMut` uses `CursorState<'a, I, ReadWrite>` to manage its state, where all
+/// the three states are useful. Due to the COW mechansim, a node can be shared in multiple
+/// `XArray`s. In that case, the `CursorMut` will first enter the `AtNode` state as it cannot hold
+/// an exclusive reference to shared data. Just before performing the modification, it copies the
+/// shared data and creates the exclusive reference, which makes the cursor enter `AtNodeMut`
+/// state.
 enum CursorState<'a, I, O>
 where
     I: ItemEntry,
@@ -175,44 +191,30 @@ impl<'a, I: ItemEntry> CursorState<'a, I, ReadWrite> {
     }
 }
 
-/// A `Cursor` can traverse in the `XArray` and have a target `XEntry` to operate,
-/// which is stored in the `index` of `XArray`. `Cursor` can be only created by an `XArray`,
-/// and will hold its immutable reference, and can only perform read-only operations
-/// for the corresponding `XArray`.
-///
-/// When creating a cursor, it will immediately traverses to touch the target XEntry in the XArray.
-/// If the cursor cannot reach to the node that can operate the target XEntry, its state will set to `Inactive`.
-/// A Cursor can reset its target index. Once it do this, it will also immediately traverses to touch the target XEntry.
-/// A Cursor can also perform `next()` to quickly operate the XEntry at the next index.
-/// If the Cursor perform reset or next and then have a target index that is not able to touch,
-/// the Cursor's state will also set to `Inactive`.
+/// A `Cursor` can traverse in the [`XArray`] by setting or increasing the target index and can
+/// perform read-only operations to the target item represented by the target index.
 ///
-/// Hence, at any given moment when no operation is being performed, a cursor will be positioned on
-/// the XNode and be ready to operate its target XEntry. If not, it means that the cursor is not able
-/// to touch the target `XEntry`.
+/// `Cursor`s act like shared references, so multiple cursors are allowed to operate on a single
+/// `XArray` at the same time.
 ///
-/// The cursor will also record all nodes passed from the head node to the target position in `passed_node`,
-/// thereby assisting it in performing some operations that involve searching upwards.
-///
-/// Multiple Cursors are allowed to operate on a single XArray at the same time.
+/// The typical way to obtain a `Cursor` instance is to call [`XArray::cursor`].
 pub struct Cursor<'a, I, M>
 where
     I: ItemEntry,
     M: Into<XMark>,
 {
-    /// The `XArray` the cursor located in.
+    /// The `XArray` where the cursor locates.
     xa: &'a XArray<I, M>,
-    /// The target index of the cursor in the belonged `XArray`.
+    /// The target index of the cursor.
     index: u64,
-    /// Represents the current state of the cursor.
+    /// The state of the cursor.
     state: CursorState<'a, I, ReadOnly>,
-    /// Record add nodes passed from the head node to the target position.
-    /// The index is the height of the recorded node.
+    /// Ancestors of the leaf node (exclusive), starting from the root node and going down.
     ancestors: SmallVec<[&'a XNode<I>; MAX_HEIGHT]>,
 }
 
 impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
-    /// Create an `Cursor` to perform read related operations on the `XArray`.
+    /// Creates a `Cursor` to perform read-related operations in the `XArray`.
     pub(super) fn new(xa: &'a XArray<I, M>, index: u64) -> Self {
         let mut cursor = Self {
             xa,
@@ -225,8 +227,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
         cursor
     }
 
-    /// Reset the target index of the Cursor. Once set, it will immediately attempt to move the Cursor
-    ///  to touch the target XEntry.
+    /// Resets the target index to `index`.
+    ///
+    /// Once set, the cursor will be positioned on the corresponding leaf node, if the leaf node
+    /// exists.
     pub fn reset_to(&mut self, index: u64) {
         self.reset();
         self.index = index;
@@ -234,14 +238,15 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
         self.traverse_to_target();
     }
 
-    /// Return the target index of the cursor.
+    /// Returns the target index of the cursor.
     pub fn index(&self) -> u64 {
         self.index
     }
 
-    /// Move the target index of the cursor to index + 1.
-    /// If the target index's corresponding XEntry is not within the current XNode, the cursor will
-    /// move to touch the target XEntry. If the move fails, the cursor's state will be set to `Inactive`.
+    /// Increases the target index of the cursor by one.
+    ///
+    /// Once increased, the cursor will be positioned on the corresponding leaf node, if the leaf
+    /// node exists.
     pub fn next(&mut self) {
         self.index = self.index.checked_add(1).unwrap();
 
@@ -267,10 +272,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
         self.continue_traverse_to_target();
     }
 
-    /// Load the `XEntry` at the current cursor index within the `XArray`.
+    /// Loads the item at the target index.
     ///
-    /// Returns a reference to the `XEntry` at the target index if succeed.
-    /// If the cursor cannot reach to the target index, the method will return `None`.
+    /// If the target item exists, this method will return a [`ItemRef`] that acts exactly like a
+    /// `&'a I` wrapped in `Some(_)`. Otherwises, it will return `None`.
     pub fn load(&mut self) -> Option<ItemRef<'a, I>> {
         self.traverse_to_target();
         self.state
@@ -278,8 +283,9 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
             .and_then(|(node, off)| node.entry(off).as_item_ref())
     }
 
-    /// Judge if the target item is marked with the input `mark`.
-    /// If target item does not exist, the function will return `None`.
+    /// Checks whether the target item is marked with the input `mark`.
+    ///
+    /// If the target item does not exist, this method will also return false.
     pub fn is_marked(&mut self, mark: M) -> bool {
         self.traverse_to_target();
         self.state
@@ -288,10 +294,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
             .unwrap_or(false)
     }
 
-    /// Traverse the XArray and move to the node that can operate the target entry.
-    /// It then returns the reference to the `XEntry` stored in the slot corresponding to the target index.
-    /// A target operated XEntry must be an item entry.
-    /// If can not touch the target entry, the function will return `None`.
+    /// Traverses from the root node to the leaf node according to the target index, if necessary
+    /// and possible.
+    ///
+    /// This methold should be called before any read-only operations.
     fn traverse_to_target(&mut self) {
         if self.state.is_at_node() {
             return;
@@ -307,6 +313,11 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
         self.continue_traverse_to_target();
     }
 
+    /// Traverses from an interior node to the leaf node according to the target index, if
+    /// possible.
+    ///
+    /// This is a helper function for internal use. Users should call
+    /// [`Cursor::traverse_to_target`] instead.
     fn continue_traverse_to_target(&mut self) {
         while !self.state.is_leaf() {
             let (current_node, operation_offset) =
@@ -325,13 +336,19 @@ impl<'a, I: ItemEntry, M: Into<XMark>> Cursor<'a, I, M> {
         }
     }
 
-    /// Initialize the Cursor to its initial state.
+    /// Resets the cursor to the inactive state.
     fn reset(&mut self) {
         self.state = CursorState::default();
         self.ancestors.clear();
     }
 }
 
+/// A dormant mutable reference to a value of `XNode<I>`.
+///
+/// While the mutable reference is dormant, a subtree of the node can continue to be operated. When
+/// the operation is finished (i.e., all references to the subtree are dead), `awaken` or
+/// `awaken_modified` (depending on whether the marks on the subtree have been updated) can be
+/// called to restore the original reference to the node.
 struct NodeMutRef<'a, I>
 where
     I: ItemEntry,
@@ -340,75 +357,79 @@ where
 }
 
 impl<'a, I: ItemEntry> NodeMutRef<'a, I> {
+    /// Creates a dormant reference for the given `node` and gets a mutable reference for the
+    /// operation on a subtree of the node (specified in `operation_offset`).
     fn new(node: &'a mut XNode<I>, operation_offset: u8) -> (&'a mut XEntry<I>, NodeMutRef<'a, I>) {
         let (node, inner) = DormantMutRef::new(node);
         (node.entry_mut(operation_offset), NodeMutRef { inner })
     }
 
+    /// Restores the original node reference after the operation on the subtree is finished.
+    ///
+    /// This method does not update the mark corresponding to the subtree, so it should only be
+    /// used when the marks on the subtree are not changed.
+    ///
+    /// # Safety
+    ///
+    /// Users must ensure all references to the subtree are now dead.
     unsafe fn awaken(self) -> &'a mut XNode<I> {
-        self.inner.awaken()
+        // SAFETY: The safety requirements of the method ensure that the original reference and all
+        // its derived references are dead.
+        unsafe { self.inner.awaken() }
     }
 
+    /// Restores the original node reference after the operation on the subtree is finished and
+    /// updates the mark corresponding to the subtree.
+    ///
+    /// The `operation_offset` in [`NodeMutRef::new`] is not stored, so users must call this method
+    /// with the `last_index` to identify the subtree on which the marks are changed.
+    ///
+    /// # Safety
+    ///
+    /// Users must ensure all references to the subtree are now dead.
     unsafe fn awaken_modified(self, last_index: u64) -> (&'a mut XNode<I>, bool) {
+        // SAFETY: The safety requirements of the method ensure that the original reference and all
+        // its derived references are dead.
         let node = unsafe { self.inner.awaken() };
         let changed = node.update_mark(node.height().height_offset(last_index));
         (node, changed)
     }
 }
 
-/// A `CursorMut` can traverse in the `XArray` and have a target `XEntry` to operate,
-/// which is stored in the `index` of `XArray`. `CursorMut` can be only created by an `XArray`,
-/// and will hold its mutable reference, and can perform read and write operations
-/// for the corresponding `XArray`.
-///
-/// When creating a `CursorMut`, it will immediately traverses to touch the target XEntry in the XArray.
-/// If the `CursorMut` cannot reach to the node that can operate the target XEntry,
-/// its state will set to `Inactive`. A `CursorMut` can reset its target index.
-/// Once it do this, it will also immediately traverses to touch the target XEntry.  
-/// A `CursorMut` can also perform `next()` to quickly operate the XEntry at the next index.
-/// If the `CursorMut` perform reset or next and then have a target index that is not able to touch,
-/// the `CursorMut`'s state will also set to `Inactive`.  
-///
-/// When CursorMut performs `reset_to()` and `next()` methods and moves its index,
-/// the CursorMut will no longer be exclusive.
-///
-/// Hence, at any given moment when no operation is being performed, a `CursorMut` will be
-/// positioned on the XNode and be ready to operate its target XEntry. If not, it means that the `CursorMut`
-/// is not able to touch the target `XEntry`. For this situation, the `CursorMut`
-/// can invoke `store` method which will expand the XArray to guarantee to reach the target position.
+/// A `CursorMut` can traverse in the [`XArray`] by setting or increasing the target index and can
+/// perform read-write operations to the target item represented by the target index.
 ///
-/// The `CursorMut` will also record all nodes passed from the head node to the target position
-/// in passed_node, thereby assisting it in performing some operations that involve searching upwards.
+/// `CursorMut`s act like exclusive references, so multiple cursors are not allowed to operate on a
+/// single `XArray` at the same time.
 ///
-/// **Features for COW (Copy-On-Write).** The CursorMut guarantees that if it is exclusive,
-/// all nodes it traverses during the process are exclusively owned by the current XArray.
-/// If it finds that the node it is about to access is shared with another XArray due to a COW clone,
-/// it will trigger a COW to copy and create an exclusive node for access. Additionally,
-/// since it holds a mutable reference to the current XArray, it will not conflict with
-/// any other cursors on the XArray. CursorMut is set to exclusive when a modification
-/// is about to be performed
+/// The typical way to obtain a `CursorMut` instance is to call [`XArray::cursor_mut`].
 ///
-/// When a CursorMut doing write operation on XArray, it should not be affected by other CursorMuts
-/// or affect other Cursors.
+/// **Features for COW (Copy-On-Write).** Due to COW, multiple `XArray`s can share the same piece
+/// of data. As a result, `CursorMut` does not always have exclusive access to the items stored in
+/// the `XArray`. However, just before performing the modification, `CursorMut` will create
+/// exclusive copies by cloning shared items, which guarantees the isolation of data stored in
+/// different `XArray`s.
 pub struct CursorMut<'a, I, M>
 where
     I: ItemEntry,
     M: Into<XMark>,
 {
-    /// The `XArray` the cursor located in.
+    /// The `XArray` where the cursor locates.
     xa: DormantMutRef<'a, XArray<I, M>>,
-    /// The target index of the cursor in the belonged `XArray`.
+    /// The target index of the cursor.
     index: u64,
-    /// Represents the current state of the cursor.
+    /// The state of the cursor.
     state: CursorState<'a, I, ReadWrite>,
-    /// Record add nodes passed from the head node to the target position.
-    /// The index is the height of the recorded node.
+    /// Ancestors of the leaf node (exclusive), starting from the root node and going down, until
+    /// the first node which is shared in multiple `XArray`s.
     mut_ancestors: SmallVec<[NodeMutRef<'a, I>; MAX_HEIGHT]>,
+    /// Ancestors of the leaf node (exclusive), but only containing the nodes which are shared in
+    /// multiple `XArray`s, from the first one and going down.
     ancestors: SmallVec<[&'a XNode<I>; MAX_HEIGHT]>,
 }
 
 impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
-    /// Create an `CursorMut` to perform read and write operations on the `XArray`.
+    /// Create a `CursorMut` to perform read- and write-related operations in the `XArray`.
     pub(super) fn new(xa: &'a mut XArray<I, M>, index: u64) -> Self {
         let mut cursor = Self {
             xa: DormantMutRef::new(xa).1,
@@ -422,8 +443,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         cursor
     }
 
-    /// Reset the target index of the Cursor. Once set, it will immediately attempt to move the
-    /// Cursor to touch the target XEntry.
+    /// Resets the target index to `index`.
+    ///
+    /// Once set, the cursor will be positioned on the corresponding leaf node, if the leaf node
+    /// exists.
     pub fn reset_to(&mut self, index: u64) {
         self.reset();
         self.index = index;
@@ -431,15 +454,15 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.traverse_to_target();
     }
 
-    /// Return the target index of the cursor.
+    /// Returns the target index of the cursor.
     pub fn index(&self) -> u64 {
         self.index
     }
 
-    /// Move the target index of the cursor to index + 1.
-    /// If the target index's corresponding XEntry is not within the current XNode, the cursor
-    /// will move to touch the target XEntry. If the move fails, the cursor's state will be
-    /// set to `Inactive`.
+    /// Increases the target index of the cursor by one.
+    ///
+    /// Once increased, the cursor will be positioned on the corresponding leaf node, if the leaf
+    /// node exists.
     pub fn next(&mut self) {
         self.index = self.index.checked_add(1).unwrap();
 
@@ -459,6 +482,8 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             let parent_node = if let Some(node) = self.ancestors.pop() {
                 NodeMaybeMut::Shared(node)
             } else if let Some(node) = self.mut_ancestors.pop() {
+                // SAFETY: All references derived from the tail node in `self.mut_ancestors` live
+                // in `self.ancestors` and `self.state`, which has already been reset.
                 NodeMaybeMut::Exclusive(unsafe { node.awaken_modified(self.index - 1).0 })
             } else {
                 self.reset();
@@ -473,10 +498,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.continue_traverse_to_target();
     }
 
-    /// Load the `XEntry` at the current cursor index within the `XArray`.
+    /// Loads the item at the target index.
     ///
-    /// Returns a reference to the `XEntry` at the target index if succeed.
-    /// If the cursor cannot reach to the target index, the method will return `None`.
+    /// If the target item exists, this method will return a [`ItemRef`] that acts exactly like a
+    /// `&'_ I` wrapped in `Some(_)`. Otherwises, it will return `None`.
     pub fn load(&mut self) -> Option<ItemRef<'_, I>> {
         self.traverse_to_target();
         self.state
@@ -484,8 +509,9 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .and_then(|(node, off)| node.entry(off).as_item_ref())
     }
 
-    /// Judge if the target item is marked with the input `mark`.
-    /// If target item does not exist, the function will return `None`.
+    /// Checks whether the target item is marked with the input `mark`.
+    ///
+    /// If the target item does not exist, this method will also return false.
     pub fn is_marked(&mut self, mark: M) -> bool {
         self.traverse_to_target();
         self.state
@@ -494,11 +520,7 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .unwrap_or(false)
     }
 
-    /// Stores the provided `XEntry` in the `XArray` at the position indicated by the current cursor index.
-    ///
-    /// If the provided entry is the same as the current entry at the cursor position,
-    /// the method returns the provided entry without making changes.
-    /// Otherwise, it replaces the current entry with the provided one and returns the old entry.
+    /// Stores a new `item` at the target index, and returns the old item if it previously exists.
     pub fn store(&mut self, item: I) -> Option<I> {
         self.expand_and_traverse_to_target();
         self.state
@@ -506,10 +528,7 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .and_then(|(node, off)| node.set_entry(off, XEntry::from_item(item)).into_item())
     }
 
-    /// Removes the `XEntry` at the target index of the 'CursorMut' within the `XArray`.
-    ///
-    /// This is achieved by storing an empty `XEntry` at the target index using the `store` method.
-    /// The method returns the replaced `XEntry` that was previously stored at the target index.
+    /// Removes the item at the target index, and returns the removed item if it previously exists.
     pub fn remove(&mut self) -> Option<I> {
         self.ensure_exclusive_before_modification();
         self.state
@@ -517,12 +536,11 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .and_then(|(node, off)| node.set_entry(off, XEntry::EMPTY).into_item())
     }
 
-    /// Mark the item at the target index in the `XArray` with the input `mark`.
-    /// If the item does not exist, return an Error.
-    ///
-    /// This operation will also mark all nodes along the path from the head node to the target node
-    /// with the input `mark`, because a marked intermediate node should be equivalent to
-    /// having a child node that is marked.
+    /// Sets the input `mark` for the item at the target index if the target item exists, otherwise
+    /// returns an error.
+    //
+    // The marks on the ancestors of the leaf node also need to be updated, which will be done
+    // later in `NodeMutRef::awaken_modified`.
     pub fn set_mark(&mut self, mark: M) -> Result<(), ()> {
         self.ensure_exclusive_before_modification();
         self.state
@@ -532,11 +550,11 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .ok_or(())
     }
 
-    /// Unset the input `mark` for the item at the target index in the `XArray`.
-    /// If the item does not exist, return an Error.
-    ///
-    /// This operation will also unset the input `mark` for all nodes along the path from the head node
-    /// to the target node if the input `mark` have not marked any of their children.
+    /// Unsets the input `mark` for the item at the target index if the target item exists,
+    /// otherwise returns an error.
+    //
+    // The marks on the ancestors of the leaf node also need to be updated, which will be done
+    // later in `NodeMutRef::awaken_modified`.
     pub fn unset_mark(&mut self, mark: M) -> Result<(), ()> {
         self.ensure_exclusive_before_modification();
         self.state
@@ -546,15 +564,17 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
             .ok_or(())
     }
 
-    /// Traverse the XArray and move to the node that can operate the target entry.
-    /// It then returns the reference to the `XEntry` stored in the slot corresponding to the target index.
-    /// A target operated XEntry must be an item entry.
-    /// If can not touch the target entry, the function will return `None`.
+    /// Traverses from the root node to the leaf node according to the target index, without
+    /// creating new nodes, if necessary and possible.
+    ///
+    /// This method should be called before any read-only operations.
     fn traverse_to_target(&mut self) {
         if self.state.is_at_node() {
             return;
         }
 
+        // SAFETY: The cursor is inactive. There are no alive references derived from the value of
+        // `&mut XArray<I, M>`.
         let xa = unsafe { self.xa.reborrow() };
 
         let max_index = xa.max_index();
@@ -567,14 +587,10 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.continue_traverse_to_target();
     }
 
-    /// Traverse the XArray and move to the node that can operate the target entry.
-    /// During the traverse, the cursor may modify the XArray to let itself be able to reach the target node.
+    /// Traverses from the root node to the leaf node according to the target index, potentially
+    /// with creating new nodes, if necessary.
     ///
-    /// Before traverse, the cursor will first expand the height of `XArray` to make sure it have enough capacity.
-    /// During the traverse, the cursor will allocate new `XNode` and put it in the appropriate slot if needed.
-    ///
-    /// It then returns the reference to the `XEntry` stored in the slot corresponding to the target index.
-    /// A target operated XEntry must be an item entry.
+    /// This method should be called before any create-if-not-exist operations.
     fn expand_and_traverse_to_target(&mut self) {
         if self.state.is_at_node() {
             self.ensure_exclusive_before_modification();
@@ -582,6 +598,8 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         }
 
         let head = {
+            // SAFETY: The cursor is inactive. There are no alive references derived from the value
+            // of `&mut XArray<I, M>`.
             let xa = unsafe { self.xa.reborrow() };
             xa.reserve(self.index);
             xa.head_mut().as_node_mut_or_cow().unwrap()
@@ -591,6 +609,9 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.exclusively_traverse_to_target();
     }
 
+    /// Ensures the exclusive access to the leaf node by copying data when necessary.
+    ///
+    /// This method should be called before any modify-if-exist operations.
     fn ensure_exclusive_before_modification(&mut self) {
         if self.state.is_at_node_mut() {
             return;
@@ -600,8 +621,12 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.ancestors.clear();
 
         let node = match self.mut_ancestors.pop() {
+            // SAFETY: All references derived from the tail node in `self.mut_ancestors` live in
+            // `self.ancestors` and `self.state`, which has already been reset.
             Some(node) => unsafe { node.awaken() },
             None => {
+                // SAFETY: All references derived from `self.xa` live in `self.mut_ancestors`,
+                // `self.ancestors`, and `self.state`. All of them have already been cleared.
                 let xa = unsafe { self.xa.reborrow() };
 
                 let head = xa.head_mut();
@@ -617,6 +642,11 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         self.exclusively_traverse_to_target();
     }
 
+    /// Traverses from an interior node to the leaf node according to the target index, without
+    /// creating new nodes, if possible.
+    ///
+    /// This is a helper function for internal use. Users should call
+    /// [`CursorMut::traverse_to_target`] instead.
     fn continue_traverse_to_target(&mut self) {
         while !self.state.is_leaf() {
             let (current_node, operation_offset) = core::mem::take(&mut self.state)
@@ -652,6 +682,12 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         }
     }
 
+    /// Traverses from an interior node to the leaf node according to the target index, potentially
+    /// with creating new nodes.
+    ///
+    /// This is a helper function for internal use. Users should call
+    /// [`CursorMut::expand_and_traverse_to_target`] or
+    /// [`CursorMut::ensure_exclusive_before_modification`] instead.
     fn exclusively_traverse_to_target(&mut self) {
         while !self.state.is_leaf() {
             let (current_node, operation_offset) =
@@ -671,12 +707,15 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
         }
     }
 
-    /// Initialize the Cursor to its initial state.
+    /// Updates marks on ancestors if necessary and resets the cursor to the inactive state.
     fn reset(&mut self) {
         self.state = CursorState::default();
         self.ancestors.clear();
 
         while let Some(node) = self.mut_ancestors.pop() {
+            // SAFETY: All references derived from the node in `self.mut_ancestors` live in the
+            // following part of `self.mut_ancestors`, `self.ancestors`, and `self.state`, which
+            // has already been cleared.
             let (_, changed) = unsafe { node.awaken_modified(self.index) };
             if !changed {
                 self.mut_ancestors.clear();
@@ -688,6 +727,7 @@ impl<'a, I: ItemEntry, M: Into<XMark>> CursorMut<'a, I, M> {
 
 impl<'a, I: ItemEntry, M: Into<XMark>> Drop for CursorMut<'a, I, M> {
     fn drop(&mut self) {
+        // This updates marks on ancestors if necessary.
         self.reset();
     }
 }

src/entry.rs

@@ -6,51 +6,64 @@ use core::ops::{Deref, Not};
 
 use crate::node::{TryClone, XNode};
 
-/// A trait that should be implemented for the types users wish to store in an `XArray`.
-/// Items stored in an XArray are required to be 8 bytes in size, Currently it can be various pointer types.
+/// A trait for the types users wish to store in an `XArray`.
+///
+/// Items stored in an `XArray` must be representable by a `usize` aligned to 4.
 ///
 /// # Safety
-/// Users must ensure that the produced `usize` of `into_raw()` meets the requirements for an item entry
-/// in the XArray. Specifically, if the original type is a pointer, the last two bits should be 00;
-/// if the original type is a value like usize, the last bit should be 1 (TODO).
+///
+/// Users must ensure that `into_raw()` always produce `usize`s that meet the above alignment
+/// requirements.
+///
+/// Users must also ensure that as long as the value does not get dropped (e.g., by making use of
+/// [`core::mem::ManuallyDrop`]), it is legal to invoke [`ItemEntry::from_raw`] multiple times on
+/// the raw `usize` produced by invoking [`ItemEntry::into_raw`] only one time.
 pub unsafe trait ItemEntry {
-    /// Converts the original type into a `usize`, consuming the ownership of the original type.
-    ///
-    /// This `usize` should be directly stored in an XArray's XEntry.
+    /// Converts the original value into a `usize`, consuming the ownership of the original value.
     fn into_raw(self) -> usize;
 
-    /// Recovers the original type from a usize, reclaiming ownership.
+    /// Recovers the original value from a `usize`, reclaiming the ownership of the original value.
     ///
     /// # Safety
-    /// The raw value passed must have been produced by the corresponding `into_raw` method in this trait
-    /// from the same type.
+    ///
+    /// The original value must have not been dropped, and the raw value must be previously
+    /// returned by [`ItemEntry::into_raw`].
     unsafe fn from_raw(raw: usize) -> Self;
 }
 
+// SAFETY: `Arc<T>` meets the safety requirements of `ItemEntry`.
 unsafe impl<T> ItemEntry for Arc<T> {
     fn into_raw(self) -> usize {
         let raw_ptr = Arc::into_raw(self);
-        debug_assert!(raw_ptr.is_aligned_to(4));
         raw_ptr as usize
     }
 
+    // SAFETY: `Arc::<T>::from_raw` and `Arc::<T>::into_raw` meet the safety requirements of
+    // `ItemEntry::from_raw`.
     unsafe fn from_raw(raw: usize) -> Self {
-        unsafe { Arc::from_raw(raw as *mut T) }
+        unsafe { Arc::from_raw(raw as *mut _) }
     }
 }
 
+// SAFETY: `Box<T>` meets the safety requirements of `ItemEntry`.
 unsafe impl<T> ItemEntry for Box<T> {
     fn into_raw(self) -> usize {
-        let raw_ptr = Box::into_raw(self) as *const u8;
-        debug_assert!(raw_ptr.is_aligned_to(4));
+        let raw_ptr = Box::into_raw(self);
         raw_ptr as usize
     }
 
+    // SAFETY: `Box::<T>::from_raw` and `Box::<T>::into_raw` meet the safety requirements of
+    // `ItemEntry::from_raw`.
     unsafe fn from_raw(raw: usize) -> Self {
-        Box::from_raw(raw as *mut _)
+        unsafe { Box::from_raw(raw as *mut _) }
     }
 }
 
+/// A type that behaves exactly the same as `&I`.
+///
+/// This works around some implementation limitations where `&I` must be returned, but it is not
+/// technically possible because the memory bits of the value are complexly encoded. Therefore a
+/// wrapper type that represents `&I` comes to the rescue.
 #[derive(PartialEq, Debug)]
 pub struct ItemRef<'a, I>
 where
@@ -68,18 +81,18 @@ impl<'a, I: ItemEntry> Deref for ItemRef<'a, I> {
     }
 }
 
-/// The type stored in the head of `XArray` and the slots of `XNode`s, which is the basic unit of storage
-/// within an XArray.
+/// A type serving as the basic unit of storage for `XArray`s, used in the head of the `XArray` and
+/// the slots of `XNode`s.
 ///
 /// There are the following types of `XEntry`:
-/// - Internal entries: These are invisible to users and have the last two bits set to 10. Currently `XArray`
-/// only have node entries as internal entries, which are entries that point to XNodes.
-/// - Item entries: Items stored by the user. Currently stored items can only be pointers and the last two bits
-/// of these item entries are 00.
+/// - Internal entries: These are invisible to users and have the last two bits set to 10.
+/// - Item entries: These represent user-given items and have the last two bits set to 00.
+///
+/// An `XEntry` owns the item or node that it represents. Once an `XEntry` generated from an item
+/// or an `XNode`, the ownership of the item or the `XNode` will be transferred to the `XEntry`.
 ///
-/// `XEntry` have the ownership. Once it generated from an item or a XNode, the ownership of the item or the XNode
-/// will be transferred to the `XEntry`. If the stored item in the XArray implemented Clone trait, then the XEntry
-/// in the XArray can also implement Clone trait.
+/// An `XEntry` behaves just like the item or node it represents. Therefore, if the item type `I`
+/// implements the [`Clone`] trait, the `XEntry` will also also implement the [`Clone`] trait.
 #[derive(PartialEq, Eq, Debug)]
 #[repr(transparent)]
 pub(super) struct XEntry<I>
@@ -117,6 +130,9 @@ impl<I: ItemEntry> XEntry<I> {
         _marker: PhantomData,
     };
 
+    // SAFETY: `ptr` must be returned from `Arc::<XNode<I>>::into_raw` or `I::into_raw` and be
+    // consistent with `ty`. In addition, the ownership of the value of `Arc<XNode<I>>` or `I` must
+    // be transferred to the constructed instance of `XEntry`.
     unsafe fn new(ptr: usize, ty: EntryType) -> Self {
         debug_assert!(ptr & Self::TYPE_MASK == 0);
         Self {
@@ -165,6 +181,8 @@ impl<I: ItemEntry> XEntry<I> {
             let arc_node = Arc::new(node);
             Arc::into_raw(arc_node) as usize
         };
+        // SAFETY: `node_ptr` is returned from `Arc::<Node<I>>::into_raw` and the ownership of the
+        // value of `Arc<XNode<I>>` is transferred.
         unsafe { Self::new(node_ptr, EntryType::Node) }
     }
 
@@ -177,15 +195,20 @@ impl<I: ItemEntry> XEntry<I> {
             return None;
         }
 
+        // SAFETY: `self` owns the value of `Arc<XNode<I>>`.
         Some(unsafe { &*(self.ptr() as *const XNode<I>) })
     }
 
     pub fn as_node_maybe_mut(&mut self) -> Option<NodeMaybeMut<'_, I>> {
         match self.node_strong_count() {
             0 => None,
+            // SAFETY: `&mut self` ensures the exclusive access to the value of `Arc<XNode<I>>`,
+            // and `node_strong_count() == 1` ensures the exclusive access to the value of
+            // `XNode<I>`.
             1 => Some(NodeMaybeMut::Exclusive(unsafe {
                 &mut *(self.ptr() as *mut _)
             })),
+            // SAFETY: `self` owns the value of `Arc<XNode<I>>`.
             _ => Some(NodeMaybeMut::Shared(unsafe { &*(self.ptr() as *const _) })),
         }
     }
@@ -193,14 +216,19 @@ impl<I: ItemEntry> XEntry<I> {
     pub fn as_node_mut_or_cow(&mut self) -> Option<&mut XNode<I>> {
         match self.node_strong_count() {
             0 => return None,
+            // SAFETY: `&mut self` ensures the exclusive access to the value of `Arc<XNode<I>>`,
+            // and `node_strong_count() == 1` ensures the exclusive access to the value of
+            // `XNode<I>`.
             1 => return Some(unsafe { &mut *(self.ptr() as *mut _) }),
             _ => (),
         }
 
+        // SAFETY: `self` owns the value of `Arc<XNode<I>>`.
         let node = unsafe { &*(self.ptr() as *const XNode<I>) };
         let new_node = node.try_clone().unwrap();
 
         *self = Self::from_node(new_node);
+        // SAFETY: `node_strong_count() == 1` now holds.
         Some(unsafe { &mut *(self.ptr() as *mut XNode<I>) })
     }
 
@@ -209,6 +237,8 @@ impl<I: ItemEntry> XEntry<I> {
             return 0;
         }
 
+        // SAFETY: `self` owns the value of `Arc<XNode<I>>` and the constructed instance of
+        // `Arc<XNode<I>>` will not be dropped.
         let node = unsafe { ManuallyDrop::new(Arc::from_raw(self.ptr() as *const XNode<I>)) };
         Arc::strong_count(&*node)
     }
@@ -217,6 +247,8 @@ impl<I: ItemEntry> XEntry<I> {
 impl<I: ItemEntry> XEntry<I> {
     pub fn from_item(item: I) -> Self {
         let item_ptr = I::into_raw(item) as usize;
+        // SAFETY: `item_ptr` is returned from `I::from_raw` and the ownership of the value of `I`
+        // is transferred.
         unsafe { Self::new(item_ptr, EntryType::Item) }
     }
 
@@ -232,6 +264,7 @@ impl<I: ItemEntry> XEntry<I> {
         let ptr = self.ptr();
         core::mem::forget(self);
 
+        // SAFETY: `self` owns the value of `I`.
         Some(unsafe { I::from_raw(ptr) })
     }
 
@@ -242,6 +275,8 @@ impl<I: ItemEntry> XEntry<I> {
 
         let ptr = self.ptr();
 
+        // SAFETY: `self` owns the value of `I`, the constructed instance of `I` will not be
+        // dropped, and `ItemRef` only allows shared access to the instance.
         Some(ItemRef {
             item: unsafe { ManuallyDrop::new(I::from_raw(ptr)) },
             _marker: PhantomData,
@@ -253,9 +288,11 @@ impl<I: ItemEntry> Drop for XEntry<I> {
     fn drop(&mut self) {
         match self.ty() {
             None => (),
+            // SAFETY: `self` owns the value of `I`.
             Some(EntryType::Item) => unsafe {
                 I::from_raw(self.ptr());
             },
+            // SAFETY: `self` owns the value of `Arc<XNode<I>>`.
             Some(EntryType::Node) => unsafe {
                 Arc::from_raw(self.ptr() as *const XNode<I>);
             },
@@ -267,10 +304,14 @@ impl<I: ItemEntry + Clone> Clone for XEntry<I> {
     fn clone(&self) -> Self {
         match self.ty() {
             None => Self::EMPTY,
+            // SAFETY: `self` owns the value of `I`, the constructed instance of `I` will not be
+            // dropped, and `clone()` only takes a shared reference to the instance.
             Some(EntryType::Item) => unsafe {
                 let item_entry = ManuallyDrop::new(I::from_raw(self.ptr()));
                 Self::from_item((*item_entry).clone())
             },
+            // SAFETY: `self` owns the value of `Arc<XNode<T>>`, and `Arc` can be cloned by
+            // increasing its strong count.
             Some(EntryType::Node) => unsafe {
                 Arc::increment_strong_count(self.ptr() as *const XNode<I>);
                 Self {

src/lib.rs

@@ -9,7 +9,7 @@
 extern crate alloc;
 
 pub use cursor::{Cursor, CursorMut};
-pub use entry::ItemEntry;
+pub use entry::{ItemEntry, ItemRef};
 pub use mark::XMark;
 pub use range::Range;
 pub use xarray::XArray;

src/mark.rs

@@ -1,7 +1,10 @@
+/// A mark used to indicate which slots in an [`XNode`] contain items that have been marked.
+///
+/// [`Xnode`]: crate::node::XNode
+///
+/// It internally stores a `u64`, functioning as a bitmap, where each bit that is set to 1
+/// represents a slot at the corresponding offset that has been marked.
 #[derive(Debug, Clone, Copy)]
-/// A mark can be used to indicate which slots in an XNode contain items that have been marked.
-/// It internally stores a u64, functioning as a bitmap,
-/// where each bit that is set to 1 represents a slot at the corresponding offset that has been marked.
 pub(super) struct Mark {
     inner: u64,
 }
@@ -48,10 +51,14 @@ impl Mark {
     }
 }
 
-/// The mark type used in the XArray. The XArray itself and an item in it can have up to three different marks.
+/// The mark type used in the [`XArray`].
+///
+/// The `XArray` itself and an item in it can have up to three different marks.
+///
+/// Users can use a self-defined type to distinguish which kind of mark they want to set. Such a
+/// type must implement the `Into<XMark>` trait.
 ///
-/// Users can use a self-defined type to distinguish which kind of mark they want to set.
-/// Such a type must implement the `Into<XMark>` trait,
+/// [`XArray`]: crate::XArray
 pub enum XMark {
     Mark0,
     Mark1,
@@ -61,7 +68,7 @@ pub enum XMark {
 pub const NUM_MARKS: usize = 3;
 
 impl XMark {
-    /// Map the XMark to an index in the range 0 to 2.
+    /// Maps the `XMark` to an index in the range 0 to 2.
     pub(super) fn index(&self) -> usize {
         match self {
             XMark::Mark0 => 0,
@@ -71,8 +78,8 @@ impl XMark {
     }
 }
 
-/// A meaningless mark used as a default generic parameter for XArray
-/// when marking functionality is not needed.
+/// A meaningless mark used as a default generic parameter for `XArray`, indicating that the
+/// marking functionality is not needed.
 #[derive(Clone, Copy)]
 pub struct NoneMark {}
 

src/node.rs

@@ -5,11 +5,11 @@ use crate::entry::{ItemEntry, XEntry};
 use crate::mark::{Mark, NUM_MARKS};
 use crate::xarray::{BITS_PER_LAYER, SLOT_MASK, SLOT_SIZE};
 
-/// The height of an XNode within an XArray.
+/// The height of an `XNode` within an `XArray`.
 ///
-/// In an XArray, the head has the highest height, while the XNodes that directly store items are at the lowest height,
-/// with a height value of 1. Each level up from the bottom height increases the height number by 1.
-/// The height of an XArray is the height of its head.
+/// In an `XArray`, the head has the highest height, while the `XNode`s that directly store items
+/// are at the lowest height, with a height value of 1. Each level up from the bottom height
+/// increases the height number by 1. The height of an `XArray` is the height of its head.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Copy, Clone)]
 pub(super) struct Height {
     height: u8,
@@ -42,10 +42,13 @@ impl PartialOrd<u8> for Height {
 }
 
 impl Height {
+    /// Creates a `Height` directly from a height value.
     pub fn new(height: u8) -> Self {
         Self { height }
     }
 
+    /// Creates a `Height` which has the mininal height value but allows the `index`-th item to be
+    /// stored.
     pub fn from_index(index: u64) -> Self {
         let mut height = Height::new(1);
         while index > height.max_index() {
@@ -54,10 +57,12 @@ impl Height {
         height
     }
 
+    /// Goes up, which increases the height velue by one.
     pub fn go_root(&self) -> Self {
         Self::new(self.height + 1)
     }
 
+    /// Goes down, which decreases the height value by one.
     pub fn go_leaf(&self) -> Self {
         Self::new(self.height - 1)
     }
@@ -66,25 +71,23 @@ impl Height {
         (self.height - 1) * BITS_PER_LAYER as u8
     }
 
-    /// Calculate the corresponding offset for the target index at the current height.
+    /// Calculates the corresponding offset for the target index at the current height.
     pub fn height_offset(&self, index: u64) -> u8 {
         ((index >> self.height_shift()) & SLOT_MASK as u64) as u8
     }
 
-    /// Calculate the maximum index that can be represented in XArray at the current height.
+    /// Calculates the maximum index that can be represented in an `XArray` with the current
+    /// height.
     pub fn max_index(&self) -> u64 {
         ((SLOT_SIZE as u64) << self.height_shift()) - 1
     }
 }
 
-/// `XNode` is the intermediate node in the tree-like structure of XArray.
+/// The `XNode` is the intermediate node in the tree-like structure of the `XArray`.
 ///
-/// It contains `SLOT_SIZE` number of XEntries, meaning it can accommodate up to `SLOT_SIZE` child nodes.
-/// The 'height' and 'offset_in_parent' attributes of an XNode are determined at initialization and remain unchanged thereafter.
-///
-/// XNode has a generic parameter called 'Operation', which has two possible instances: `ReadOnly` and `ReadWrite`.
-/// These instances indicate whether the XNode will only perform read operations or both read and write operations
-/// (where write operations imply potential modifications to the contents of slots).
+/// It contains `SLOT_SIZE` number of `XEntry`s, meaning it can accommodate up to `SLOT_SIZE` child
+/// nodes. The `height` and `offset_in_parent` attributes of an `XNode` are determined at
+/// initialization and remain unchanged thereafter.
 #[derive(Clone, Debug)]
 pub(super) struct XNode<I>
 where
@@ -94,9 +97,17 @@ where
     /// which stores the user-given items, is 1.
     height: Height,
     /// This node is its parent's `offset_in_parent`-th child.
-    /// This field is meaningless if this node is the root (will be 0).
+    ///
+    /// This field will be zero if this node is the root, as the node will be the 0-th child of its
+    /// parent once the height of `XArray` is increased.
     offset_in_parent: u8,
+    /// The slots storing `XEntry`s, which point to user-given items for leaf nodes and other
+    /// `XNode`s for interior nodes.
     slots: [XEntry<I>; SLOT_SIZE],
+    /// The marks representing whether each slot is marked or not.
+    ///
+    /// Users can set mark or unset mark on user-given items, and a leaf node or an interior node
+    /// is marked if and only if there is at least one marked item within the node.
     marks: [Mark; NUM_MARKS],
 }
 
@@ -114,7 +125,7 @@ impl<I: ItemEntry> XNode<I> {
         }
     }
 
-    /// Get the offset in the slots of the current XNode corresponding to the XEntry for the target index.
+    /// Get the slot offset at the current `XNode` for the target index `target_index`.
     pub fn entry_offset(&self, target_index: u64) -> u8 {
         self.height.height_offset(target_index)
     }
@@ -155,6 +166,15 @@ impl<I: ItemEntry> XNode<I> {
         self.height == 1
     }
 
+    /// Sets the slot at the given `offset` to the given `entry`.
+    ///
+    /// If `entry` represents an item, the old marks at the same offset will be cleared. Otherwise,
+    /// if `entry` represents a node, the marks at the same offset will be updated according to
+    /// whether the new node contains marked items.
+    ///
+    /// This method changes the mark _only_ on this `XNode'. It's the caller's responsibility to
+    /// ensure that the marks on the ancestors of this `XNode' are up to date. See also
+    /// [`XNode::update_mark`].
     pub fn set_entry(&mut self, offset: u8, entry: XEntry<I>) -> XEntry<I> {
         let is_new_node = entry.is_node();
 
@@ -171,10 +191,20 @@ impl<I: ItemEntry> XNode<I> {
         old_entry
     }
 
+    /// Sets the input `mark` at the given `offset`.
+    ///
+    /// This method changes the mark _only_ on this `XNode'. It's the caller's responsibility to
+    /// ensure that the marks on the ancestors of this `XNode' are up to date. See also
+    /// [`XNode::update_mark`].
     pub fn set_mark(&mut self, offset: u8, mark: usize) {
         self.marks[mark].set(offset);
     }
 
+    /// Unsets the input `mark` at the given `offset`.
+    ///
+    /// This method changes the mark _only_ on this `XNode'. It's the caller's responsibility to
+    /// ensure that the marks on the ancestors of this `XNode' are up to date. See also
+    /// [`XNode::update_mark`].
     pub fn unset_mark(&mut self, offset: u8, mark: usize) {
         self.marks[mark].unset(offset);
     }
@@ -183,6 +213,15 @@ impl<I: ItemEntry> XNode<I> {
         self.marks[mark].clear();
     }
 
+    /// Updates the mark at the given `offset` and returns `true` if the mark is changed.
+    ///
+    /// This method does nothing if the slot at the given `offset` does not represent a node. It
+    /// assumes the marks of the child node are up to date, and ensures the mark at the given
+    /// `offset` is also up to date.
+    ///
+    /// Whenever a mark at the leaf node changes, this method should be invoked from the leaf node
+    /// up to the root node, until the mark does not change on some node or the root node has been
+    /// reached.
     pub fn update_mark(&mut self, offset: u8) -> bool {
         let Some(node) = self.slots[offset as usize].as_node_ref() else {
             return false;

src/range.rs

@@ -2,8 +2,12 @@ use crate::cursor::Cursor;
 use crate::entry::{ItemEntry, ItemRef};
 use crate::mark::XMark;
 
-/// An iterator over a sub-range of entries in a XArray.
-/// This struct is created by the `range()` method on `XArray`.
+/// An iterator over a range of entries in an [`XArray`].
+///
+/// The typical way to obtain a `Range` instance is to call [`XArray::range`].
+///
+/// [`XArray`]: crate::XArray
+/// [`XArray::range`]: crate::XArray::range
 pub struct Range<'a, I, M>
 where
     I: ItemEntry,

src/xarray.rs

@@ -12,30 +12,30 @@ pub(super) const SLOT_SIZE: usize = 1 << BITS_PER_LAYER;
 pub(super) const SLOT_MASK: usize = SLOT_SIZE - 1;
 pub(super) const MAX_HEIGHT: usize = 64 / BITS_PER_LAYER + 1;
 
-/// `XArray` is an abstract data type functioning like an expansive array of items
-/// where each item must be an 8-byte object, such as `Arc<T>` or `Box<T>`.
-/// User-stored pointers must have a minimum alignment of 4 bytes.
-/// `XArray` facilitates efficient sequential access to adjacent entries,
-/// supporting multiple concurrent reads and exclusively allowing one write operation at a time.
+/// `XArray` is an abstract data type functioning like an expansive array of items where each item
+/// must be an 8-byte object, such as `Arc<T>` or `Box<T>`.
+///
+/// User-stored pointers must have a minimum alignment of 4 bytes. `XArray` facilitates efficient
+/// sequential access to adjacent entries, supporting multiple concurrent reads and exclusively
+/// allowing one write operation at a time.
 ///
 /// # Features
-/// **Copy-on-write (COW):** If items within `XArray` implement the `Clone` trait,
-/// cloning can leverage a COW mechanism. A clone of an `XArray` initially shares the
-/// head node with the original, avoiding immediate deep copying. If a mutable operation
-/// is required on either `XArray`, a deep copy of the relevant `XNode` is made first,
-/// ensuring isolated operations.
+/// **Copy-on-write (COW):** If items within `XArray` implement the `Clone` trait, cloning can
+/// leverage a COW mechanism. A clone of an `XArray` initially shares the head node with the
+/// original, avoiding immediate deep copying. If a mutable operation is required on either
+/// `XArray`, a deep copy of the relevant nodes is made first, ensuring isolated operations.
 ///
-/// **Cursors:** Interaction with `XArray` is mediated through `Cursor` and `CursorMut`.
-/// A `Cursor` requires an immutable reference, while `CursorMut` requires a mutable reference.
-/// As such, multiple `Cursor` instances can coexist, but `CursorMut` operations are singular,
-/// reflecting the behavior of shared (`&`) and exclusive (`&mut`) references.
-/// Cursors offer precise index positioning and traversal capabilities in the `XArray`.
+/// **Cursors:** Interaction with `XArray` is mediated through [`Cursor`] and [`CursorMut`]. A
+/// `Cursor` requires an immutable reference, while `CursorMut` requires a mutable reference. As
+/// such, multiple `Cursor` instances can coexist, but `CursorMut` operations are singular,
+/// reflecting the behavior of shared (`&`) and exclusive (`&mut`) references. Cursors offer
+/// precise index positioning and traversal capabilities in the `XArray`.
 ///
-/// **Marking:** `XArray` enables marking of individual items or the `XArray` itself for user convenience.
-/// Items and the `XArray` can have up to three distinct marks by default, with each mark independently maintained.
-/// Users can use self-defined types as marks by implementing the `From<Type>` trait for XMark.
-/// Marking is also applicable to internal nodes, indicating marked descendant nodes,
-/// though such marking is not transparent to users.
+/// **Marking:** `XArray` enables marking of individual items or the `XArray` itself for user
+/// convenience. Items and the `XArray` can have up to three distinct marks by default, with each
+/// mark independently maintained. Users can use self-defined types as marks by implementing the
+/// `From<Type>` trait for [`XMark`]. Marking is also applicable to internal nodes, indicating
+/// marked descendant nodes, though such marking is not transparent to users.
 ///
 /// # Example
 ///
@@ -58,8 +58,8 @@ pub(super) const MAX_HEIGHT: usize = 64 / BITS_PER_LAYER + 1;
 /// assert!(*xarray_clone.load(10).unwrap().as_ref() == 100);
 /// ```
 ///
-/// The concepts XArray are originally introduced by Linux, which keeps the data structure of
-/// Linux's radix tree [Linux Radix Trees](https://lwn.net/Articles/175432/).
+/// The XArray concept was originally introduced by Linux, which keeps the data structure of [Linux
+/// Radix Trees](https://lwn.net/Articles/175432/).
 pub struct XArray<I, M = NoneMark>
 where
     I: ItemEntry,
@@ -71,7 +71,7 @@ where
 }
 
 impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
-    /// Make a new, empty XArray.
+    /// Makes a new, empty `XArray`.
     pub const fn new() -> Self {
         Self {
             marks: [false; 3],
@@ -80,30 +80,32 @@ impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
         }
     }
 
-    /// Mark the `XArray` with the input `mark`.
+    /// Marks the `XArray` with the input `mark`.
     pub fn set_mark(&mut self, mark: M) {
         self.marks[mark.into().index()] = true;
     }
 
-    /// Unset the input `mark` for the `XArray`.
+    /// Unsets the input `mark` for the `XArray`.
     pub fn unset_mark(&mut self, mark: M) {
         self.marks[mark.into().index()] = false;
     }
 
-    /// Judge if the `XArray` is marked with the input `mark`.
+    /// Checks whether the `XArray` is marked with the input `mark`.
     pub fn is_marked(&self, mark: M) -> bool {
         self.marks[mark.into().index()]
     }
 
-    /// Return a reference to the head entry, and later will not modify the XNode pointed to by the `head`.
+    /// Returns a shared reference to the head `XEntry`.
     pub(super) fn head(&self) -> &XEntry<I> {
         &self.head
     }
 
+    /// Returns an exclusive reference to the head `XEntry`.
     pub(super) fn head_mut(&mut self) -> &mut XEntry<I> {
         &mut self.head
     }
 
+    /// Increases the height of the `XArray` so that the `index`-th element can be stored.
     pub(super) fn reserve(&mut self, index: u64) {
         if self.head.is_null() {
             let height = Height::from_index(index);
@@ -127,7 +129,8 @@ impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
         }
     }
 
-    /// Calculate the max index that can stored in the XArray with current height.
+    /// Calculates the maximum index of elements that can be stored with the current height of the
+    /// `XArray`.
     pub(super) fn max_index(&self) -> u64 {
         self.head()
             .as_node_ref()
@@ -135,21 +138,23 @@ impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
             .unwrap_or(0)
     }
 
-    /// Attempts to load the item at the target index within the `XArray`.
-    /// If the target item exists, return it with `Some`, Otherwise, return `None`.
+    /// Loads the `index`-th item.
+    ///
+    /// If the target item exists, it will be returned with `Some(_)`, otherwise, `None` will be
+    /// returned.
     pub fn load(&self, index: u64) -> Option<ItemRef<'_, I>> {
         let mut cursor = self.cursor(index);
         cursor.load()
     }
 
-    /// Stores the provided item in the `XArray` at the target index,
-    /// and return the old item if it was previously stored in target index.
+    /// Stores the provided item in the `XArray` at the target index, and returns the old item if
+    /// some item was previously stored in the same position.
     pub fn store(&mut self, index: u64, item: I) -> Option<I> {
         let mut cursor = self.cursor_mut(index);
         cursor.store(item)
     }
 
-    /// Unset the input `mark` for all of the items in the `XArray`.
+    /// Unsets the input `mark` for all of the items in the `XArray`.
     pub fn unset_mark_all(&mut self, mark: M) {
         let mut pending_nodes = VecDeque::new();
 
@@ -172,25 +177,25 @@ impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
         }
     }
 
-    /// Removes the `XEntry` at the target index within the `XArray`,
-    /// and return the removed item if it was previously stored in target index.
+    /// Removes the `XEntry` in the `XArray` at the target index, and returns the removed item if
+    /// some item was previously stored in the same position.
     pub fn remove(&mut self, index: u64) -> Option<I> {
         let mut cursor = self.cursor_mut(index);
         cursor.remove()
     }
 
-    /// Create an `Cursor` to perform read related operations on the `XArray`.
+    /// Creates a [`Cursor`] to perform read-related operations in the `XArray`.
     pub fn cursor(&self, index: u64) -> Cursor<'_, I, M> {
         Cursor::new(self, index)
     }
 
-    /// Create an `CursorMut` to perform read and write operations on the `XArray`.
+    /// Creates a [`CursorMut`] to perform read- and write-related operations in the `XArray`.
     pub fn cursor_mut(&mut self, index: u64) -> CursorMut<'_, I, M> {
         CursorMut::new(self, index)
     }
 
-    /// Create a `Range` which can be immutably iterated over the index corresponding to the `range`
-    /// in `XArray`.
+    /// Creates a [`Range`] which can be immutably iterated over the indexes corresponding to the
+    /// specified `range`.
     pub fn range(&self, range: core::ops::Range<u64>) -> Range<'_, I, M> {
         let cursor = Cursor::new(self, range.start);
         Range::new(cursor, range.end)
@@ -198,7 +203,7 @@ impl<I: ItemEntry, M: Into<XMark>> XArray<I, M> {
 }
 
 impl<I: ItemEntry + Clone, M: Into<XMark>> Clone for XArray<I, M> {
-    /// Clone with COW mechanism.
+    /// Clones the `XArray` with the COW mechanism.
     fn clone(&self) -> Self {
         let cloned_head = self.head.clone();
         Self {