📝 Add docstrings to cli/serial-creation

* 📝 Add docstrings to `cli/serial-creation`

Docstrings generation was requested by @ChanTsune.

* #2635 (comment)

The following files were modified:

* `cli/src/command/core.rs`
* `cli/src/command/core/iter.rs`
* `cli/src/command/create.rs`
* `cli/src/command/update.rs`
* `cli/tests/cli/append/entry_order.rs`
* `cli/tests/cli/create/entry_order.rs`
* `cli/tests/cli/update/entry_order.rs`

* ♻️ Keep only iter.rs docstrings and add unit tests

- Revert docstring changes to core.rs, create.rs, update.rs, and test files
- Keep OrderedByIndex documentation in iter.rs
- Replace doc examples with actual unit tests in mod tests

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: ChanTsune <41658782+ChanTsune@users.noreply.github.com>

Author: coderabbitai[bot]

cli/src/command/core/iter.rs

@@ -2,7 +2,18 @@ use std::collections::HashMap;
 
 /// Reorders `(usize, T)` items into index order, buffering out-of-order items.
 ///
+/// Used to preserve original argument order when parallel processing may
+/// produce results in arbitrary order.
+///
+/// # Preconditions
+///
 /// This iterator expects indices to be contiguous starting at `start`.
+/// If any index in the expected sequence is missing from the input,
+/// subsequent items will be buffered but never yielded (silently dropped).
+///
+/// Each index should appear at most once. If duplicate indices are provided,
+/// only the last item with that index will be retained (earlier items are
+/// silently overwritten).
 #[derive(Debug)]
 pub(crate) struct OrderedByIndex<I, T>
 where
@@ -17,10 +28,23 @@ impl<I, T> OrderedByIndex<I, T>
 where
     I: Iterator<Item = (usize, T)>,
 {
+    /// Creates an `OrderedByIndex` that yields items in ascending index order starting from 0.
+    ///
+    /// `iter` is the underlying iterator that yields `(index, item)` pairs;
+    /// out-of-order items are buffered until their index becomes the next expected value.
     pub(crate) fn new(iter: I) -> Self {
         Self::with_start(iter, 0)
     }
 
+    /// Creates an `OrderedByIndex` iterator that yields items starting from `start`
+    /// and buffers out-of-order items until their index becomes the next expected.
+    ///
+    /// `iter` must produce `(usize, T)` pairs where the `usize` is the item's
+    /// original index. The resulting iterator emits `T` values in ascending index
+    /// order beginning at `start`.
+    ///
+    /// See the struct-level documentation for preconditions regarding index
+    /// contiguity and uniqueness.
     pub(crate) fn with_start(iter: I, start: usize) -> Self {
         Self {
             iter,
@@ -36,6 +60,12 @@ where
 {
     type Item = T;
 
+    /// Advances the ordered iterator and yields the next item whose index matches
+    /// the current expected index.
+    ///
+    /// Returns the next buffered or incoming item with the smallest contiguous index
+    /// equal to the iterator's current expectation; when the underlying iterator is
+    /// exhausted and no matching buffered item exists, iteration ends.
     fn next(&mut self) -> Option<Self::Item> {
         loop {
             if let Some(item) = self.buffer.remove(&self.next) {
@@ -56,3 +86,45 @@ where
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn reorders_out_of_order_items() {
+        let iter = vec![(1, 20), (0, 10)].into_iter();
+        let mut ordered = OrderedByIndex::new(iter);
+        assert_eq!(ordered.next(), Some(10));
+        assert_eq!(ordered.next(), Some(20));
+        assert_eq!(ordered.next(), None);
+    }
+
+    #[test]
+    fn with_start_reorders_from_given_index() {
+        let src = vec![(2, "a"), (4, "c"), (3, "b")];
+        let out: Vec<_> = OrderedByIndex::with_start(src.into_iter(), 2).collect();
+        assert_eq!(out, vec!["a", "b", "c"]);
+    }
+
+    #[test]
+    fn handles_already_ordered_items() {
+        let items = vec![(0, 'a'), (1, 'b'), (2, 'c')];
+        let out: Vec<_> = OrderedByIndex::new(items.into_iter()).collect();
+        assert_eq!(out, vec!['a', 'b', 'c']);
+    }
+
+    #[test]
+    fn handles_reverse_order() {
+        let items = vec![(2, 'c'), (1, 'b'), (0, 'a')];
+        let out: Vec<_> = OrderedByIndex::new(items.into_iter()).collect();
+        assert_eq!(out, vec!['a', 'b', 'c']);
+    }
+
+    #[test]
+    fn handles_empty_iterator() {
+        let items: Vec<(usize, i32)> = vec![];
+        let out: Vec<_> = OrderedByIndex::new(items.into_iter()).collect();
+        assert!(out.is_empty());
+    }
+}

cli/src/command/update.rs

@@ -560,6 +560,10 @@ where
                         });
                         Ok(None)
                     } else {
+                        // NOTE: Entry doesn't need update - write it directly to archive.
+                        // We still send a placeholder to the channel to maintain index
+                        // continuity for OrderedByIndex, preventing it from blocking
+                        // on this index forever.
                         tx.send((idx, Ok(None)))
                             .unwrap_or_else(|e| log::error!("{e}: {}", entry.header().path()));
                         Ok(Some(entry))
@@ -636,6 +640,10 @@ where
                         });
                         Ok(None)
                     } else {
+                        // NOTE: Entry doesn't need update - write it directly to archive.
+                        // We still send a placeholder to the channel to maintain index
+                        // continuity for OrderedByIndex, preventing it from blocking
+                        // on this index forever.
                         tx.send((idx, Ok(None)))
                             .unwrap_or_else(|e| log::error!("{e}: {}", entry.header().path()));
                         Ok(Some(entry))