Path::with_extension: improve examples

library/std/src/path.rs

@@ -2743,12 +2743,27 @@ impl Path {
  ///
  /// let path = Path::new("foo.rs");
  /// assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt"));
+ /// assert_eq!(path.with_extension(""), PathBuf::from("foo"));
+ /// ```
+ ///
+ /// Handling multiple extensions:
+ ///
+ /// ```
+ /// use std::path::{Path, PathBuf};
  ///
  /// let path = Path::new("foo.tar.gz");
- /// assert_eq!(path.with_extension(""), PathBuf::from("foo.tar"));
  /// assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz"));
  /// assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt"));
  /// ```
+ ///
+ /// Adding an extension where one did not exist:
+ ///
+ /// ```
+ /// use std::path::{Path, PathBuf};
+ ///
+ /// let path = Path::new("foo");
+ /// assert_eq!(path.with_extension("rs"), PathBuf::from("foo.rs"));
+ /// ```
  #[stable(feature = "rust1", since = "1.0.0")]
  pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {
  self._with_extension(extension.as_ref())