diff --git a/library/std/src/path.rs b/library/std/src/path.rs index 07f212b113564..5be2e0ae41f7e 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -19,6 +19,20 @@ //! matter the platform or filesystem. An exception to this is made for Windows //! drive letters. //! +//! ## Path normalization +//! +//! Several methods in this module perform basic path normalization: +//! +//! - [`Path::components`] and [`Path::iter`] normalize away repeated separators, +//! non-leading `.` components, and trailing slashes +//! - [`PartialEq`], [`PartialOrd`], and [`Ord`] implementations +//! perform the same normalization for comparison +//! - [`Path::has_root`] and [`PathBuf::push`] also apply this normalization +//! +//! These methods **do not** resolve `..` components or symlinks. For full normalization +//! including `..` resolution, use [`Path::normalize_lexically`] (which doesn't access +//! the filesystem) or [`Path::canonicalize`] (which does access the filesystem). +//! //! ## Simple usage //! //! Path manipulation includes both parsing components from slices and building