Repository: rust-lang/rust
File: library/std/src/path.rs (Rust)

Code before:
//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
//! correspond to the substrings between path separators (`/` or `\`). You can
//! reconstruct an equivalent path from components with the [`push`] method on
//! [`PathBuf`]; note that the paths may differ syntactically by the
//! normalization described in the documentation for the [`components`] method.
//!
//! ## Case sensitivity
//!
//! Unless otherwise indicated path methods that do not access the filesystem,
//! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no
//! 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<Path>`], [`PartialOrd<Path>`], and [`Ord<Path>`] 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
//! new owned paths.
//!
//! To parse a path, you can create a [`Path`] slice from a [`str`]
//! slice and start asking questions:
//!
//! ```
//! use std::path::Path;
//! use std::ffi::OsStr;
//!
//! let path = Path::new("/tmp/foo/bar.txt");
//!
//! let parent = path.parent();
//! assert_eq!(parent, Some(Path::new("/tmp/foo")));
//!
//! let file_stem = path.file_stem();
//! assert_eq!(file_stem, Some(OsStr::new("bar")));
//!
//! let extension = path.extension();
//! assert_eq!(extension, Some(OsStr::new("txt")));
//! ```
//!

Review comment (suggestion):
We shouldn't mention `normalize_lexically` since it is unstable

Code after:
//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
//! correspond to the substrings between path separators (`/` or `\`). You can
//! reconstruct an equivalent path from components with the [`push`] method on
//! [`PathBuf`]; note that the paths may differ syntactically by the
//! normalization described in the documentation for the [`components`] method.
//!
//! ## Case sensitivity
//!
//! Unless otherwise indicated path methods that do not access the filesystem,
//! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no
//! 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 by disregarding
//! repeated separators, non-leading `.` components, and trailing separators. These include:
//! - Methods for iteration, such as [`Path::components`] and [`Path::iter`]
//! - Methods for inspection, such as [`Path::has_root`]
//! - Comparisons using [`PartialEq`], [`PartialOrd`], and [`Ord`]
//!
//! [`Path::join`] and [`PathBuf::push`] also disregard trailing slashes.
//!
// FIXME(normalize_lexically): mention normalize_lexically once stable
//! These methods **do not** resolve `..` components or symlinks. For full normalization
//! including `..` resolution, use [`Path::canonicalize`] (which does access the filesystem).
//!
//! ## Simple usage
//!
//! Path manipulation includes both parsing components from slices and building
//! new owned paths.
//!
//! To parse a path, you can create a [`Path`] slice from a [`str`]
//! slice and start asking questions:
//!
//! ```
//! use std::path::Path;
//! use std::ffi::OsStr;
//!
//! let path = Path::new("/tmp/foo/bar.txt");
//!
//! let parent = path.parent();
//! assert_eq!(parent, Some(Path::new("/tmp/foo")));
//!
//! let file_stem = path.file_stem();
//! assert_eq!(file_stem, Some(OsStr::new("bar")));
//!
//! let extension = path.extension();
//! assert_eq!(extension, Some(OsStr::new("txt")));
//! ```
//!