From 09e769d786ac620959246ac77657e9029c728c46 Mon Sep 17 00:00:00 2001
From: Bloxx12 <charlie@charlieroot.dev>
Date: Fri, 9 May 2025 22:35:26 +0200
Subject: [PATCH] diff: improve docs

Co-Authored-By: RGBCube <git@rgbcu.be>
---
 src/diff.rs    | 31 ++++++++++++++++++++++++++-----
 src/version.rs | 12 +++++++-----
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/src/diff.rs b/src/diff.rs
index 1859000..38a7beb 100644
--- a/src/diff.rs
+++ b/src/diff.rs
@@ -55,8 +55,10 @@ impl DiffStatus {
 
 /// Writes the diff header (<<< out, >>>in) and package diff.
 ///
-/// Returns the amount of package diffs written. Even when zero, the header will
-/// be written.
+/// # Returns
+///
+/// Will return the amount of package diffs written. Even when zero,
+/// the header will be written.
 pub fn write_paths_diffln(
   writer: &mut impl fmt::Write,
   path_old: &Path,
@@ -112,13 +114,28 @@ pub fn write_paths_diffln(
   )?)
 }
 
+/// Takes a list of versions which may contain duplicates and deduplicates it by
+/// replacing multiple occurrences of an element with the same element plus the
+/// amount it occurs.
+///
+/// # Example
+///
+/// ```rs
+/// let mut versions = vec!["2.3", "1.0", "2.3", "4.8", "2.3", "1.0"];
+///
+/// deduplicate_versions(&mut versions);
+/// assert_eq!(*versions, &["1.0 ×2", "2.3 ×3", "4.8"]);
+/// ```
 fn deduplicate_versions(versions: &mut Vec<Version>) {
   versions.sort_unstable();
 
   let mut deduplicated = Vec::new();
+
+  // Push a version onto the final vec. If it occurs more than once,
+  // we add a ×{count} to signify the amount of times it occurs.
   let mut deduplicated_push = |mut version: Version, count: usize| {
     if count > 1 {
-      write!(version, " * {count}").unwrap();
+      write!(version, " ×{count}").unwrap();
     }
     deduplicated.push(version);
   };
@@ -131,6 +148,8 @@ fn deduplicate_versions(versions: &mut Vec<Version>) {
       continue;
     };
 
+    // If the last version matches the current version, we increase the count by
+    // one. Otherwise, we push the last version to the result.
     if last_version_value == *version {
       last_version = Some((last_version_value, count + 1));
     } else {
@@ -138,6 +157,7 @@ fn deduplicate_versions(versions: &mut Vec<Version>) {
     }
   }
 
+  // Push the final element, if it exists.
   if let Some((version, count)) = last_version.take() {
     deduplicated_push(version, count);
   }
@@ -145,6 +165,7 @@ fn deduplicate_versions(versions: &mut Vec<Version>) {
   *versions = deduplicated;
 }
 
+#[expect(clippy::cognitive_complexity, clippy::too_many_lines)]
 fn write_packages_diffln<'a>(
   writer: &mut impl fmt::Write,
   paths_old: impl Iterator<Item = &'a StorePath>,
@@ -162,7 +183,7 @@ fn write_packages_diffln<'a>(
           .entry(name)
           .or_default()
           .old
-          .push(version.unwrap_or(Version::from("<none>".to_owned())));
+          .push(version.unwrap_or_else(|| Version::from("<none>".to_owned())));
       },
 
       Err(error) => {
@@ -181,7 +202,7 @@ fn write_packages_diffln<'a>(
           .entry(name)
           .or_default()
           .new
-          .push(version.unwrap_or(Version::from("<none>".to_owned())));
+          .push(version.unwrap_or_else(|| Version::from("<none>".to_owned())));
       },
 
       Err(error) => {
diff --git a/src/version.rs b/src/version.rs
index 0fb13db..24386bf 100644
--- a/src/version.rs
+++ b/src/version.rs
@@ -77,10 +77,12 @@ impl<'a> Iterator for VersionComponentIter<'a> {
   type Item = Result<VersionComponent<'a>, &'a str>;
 
   fn next(&mut self) -> Option<Self::Item> {
-    if self.starts_with(['.', '-', '*', ' ']) {
-      let ret = &self[..1];
-      **self = &self[1..];
-      return Some(Err(ret));
+    if self.starts_with(['.', '-', '*', '×', ' ']) {
+      let len = self.chars().next().unwrap().len_utf8();
+      let (this, rest) = self.split_at(len);
+
+      **self = rest;
+      return Some(Err(this));
     }
 
     // Get the next character and decide if it is a digit.
@@ -91,7 +93,7 @@ impl<'a> Iterator for VersionComponentIter<'a> {
       .chars()
       .take_while(|&char| {
         char.is_ascii_digit() == is_digit
-          && !matches!(char, '.' | '-' | '*' | ' ')
+          && !matches!(char, '.' | '-' | '*' | ' ' | '×')
       })
       .map(char::len_utf8)
       .sum();