1 files changed, 45 insertions, 33 deletions
diff --git a/utils/string_proc/src/format_path.rs b/utils/string_proc/src/format_path.rs
index 35689b8..8750db6 100644
--- a/utils/string_proc/src/format_path.rs
+++ b/utils/string_proc/src/format_path.rs
@@ -1,6 +1,41 @@
 use std::path::{Path, PathBuf};
 
-/// Format path str
+/// Normalize an input path string into a canonical, platform‑agnostic form.
+///
+/// This function removes ANSI escape sequences, unifies separators to `/`,
+/// collapses duplicate slashes, strips unfriendly characters (`*`, `?`, `"`, `<`, `>`, `|`),
+/// resolves simple `..` components, and preserves a trailing slash when present.
+///
+/// See examples below for the exact normalization behavior.
+///
+/// # Examples
+///
+/// ```
+/// # use string_proc::format_path::format_path_str;
+/// use std::io::Error;
+///
+/// # fn main() -> Result<(), Error> {
+/// assert_eq!(format_path_str("C:\\Users\\\\test")?, "C:/Users/test");
+/// assert_eq!(
+///     format_path_str("/path/with/*unfriendly?chars")?,
+///     "/path/with/unfriendlychars"
+/// );
+/// assert_eq!(format_path_str("\x1b[31m/path\x1b[0m")?, "/path");
+/// assert_eq!(format_path_str("/home/user/dir/")?, "/home/user/dir/");
+/// assert_eq!(
+///     format_path_str("/home/user/file.txt")?,
+///     "/home/user/file.txt"
+/// );
+/// assert_eq!(
+///     format_path_str("/home/my_user/DOCS/JVCS_TEST/Workspace/../Vault/")?,
+///     "/home/my_user/DOCS/JVCS_TEST/Vault/"
+/// );
+/// assert_eq!(format_path_str("./home/file.txt")?, "home/file.txt");
+/// assert_eq!(format_path_str("./home/path/")?, "home/path/");
+/// assert_eq!(format_path_str("./")?, "");
+/// # Ok(())
+/// # }
+/// ```
 pub fn format_path_str(path: impl Into<String>) -> Result<String, std::io::Error> {
     let path_str = path.into();
     let ends_with_slash = path_str.ends_with('/');
@@ -73,39 +108,16 @@ fn normalize_path(path: &Path) -> PathBuf {
     }
 }
 
+/// Format a [`PathBuf`] into its canonical string form and convert it back.
+///
+/// This is a convenience wrapper around [`format_path_str`], preserving
+/// the semantics of [`PathBuf`] while applying the same normalization rules:
+/// - normalize separators to `/`
+/// - remove duplicated separators
+/// - strip ANSI escape sequences
+/// - remove unfriendly characters (`*`, `?`, etc.)
+/// - resolve simple `..` segments
 pub fn format_path(path: impl Into<PathBuf>) -> Result<PathBuf, std::io::Error> {
     let path_str = format_path_str(path.into().display().to_string())?;
     Ok(PathBuf::from(path_str))
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_format_path() -> Result<(), std::io::Error> {
-        assert_eq!(format_path_str("C:\\Users\\\\test")?, "C:/Users/test");
-
-        assert_eq!(
-            format_path_str("/path/with/*unfriendly?chars")?,
-            "/path/with/unfriendlychars"
-        );
-
-        assert_eq!(format_path_str("\x1b[31m/path\x1b[0m")?, "/path");
-        assert_eq!(format_path_str("/home/user/dir/")?, "/home/user/dir/");
-        assert_eq!(
-            format_path_str("/home/user/file.txt")?,
-            "/home/user/file.txt"
-        );
-        assert_eq!(
-            format_path_str("/home/my_user/DOCS/JVCS_TEST/Workspace/../Vault/")?,
-            "/home/my_user/DOCS/JVCS_TEST/Vault/"
-        );
-
-        assert_eq!(format_path_str("./home/file.txt")?, "home/file.txt");
-        assert_eq!(format_path_str("./home/path/")?, "home/path/");
-        assert_eq!(format_path_str("./")?, "");
-
-        Ok(())
-    }
-}