Improve docs for snapshot updates (#479)

cargo-insta/src/walk.rs

@@ -35,8 +35,7 @@ pub(crate) fn find_snapshots<'a>(
             let fname = e.file_name().to_string_lossy();
             if fname.ends_with(".new") {
                 let new_path = e.into_path();
-                let mut old_path = new_path.clone();
-                old_path.set_extension("");
+                let old_path = new_path.clone().with_extension("");
                 Some(SnapshotContainer::load(
                     new_path,
                     old_path,

insta/src/lib.rs

@@ -100,56 +100,55 @@
 //! # Snapshot updating
 //!
 //! During test runs snapshots will be updated according to the `INSTA_UPDATE`
-//! environment variable.  The default is `auto` which will write all new
-//! snapshots into `.snap.new` files if no CI is detected so that
-//! [`cargo-insta`](https://crates.io/crates/cargo-insta)
-//! can pick them up.  Normally you don't have to change this variable.
+//! environment variable.  The default is `auto` which will write snapshots for
+//! any failing tests into `.snap.new` files (if no CI is detected) so that
+//! [`cargo-insta`](https://crates.io/crates/cargo-insta) can pick them up for
+//! review. Normally you don't have to change this variable.
 //!
 //! `INSTA_UPDATE` modes:
 //!
 //! - `auto`: the default. `no` for CI environments or `new` otherwise
-//! - `always`: overwrites old snapshot files with new ones unasked
-//! - `unseen`: behaves like `always` for new snapshots and `new` for others
-//! - `new`: write new snapshots into `.snap.new` files
-//! - `no`: does not update snapshot files at all (just runs tests)
-//!
-//! When `new` or `auto` is used as mode the [`cargo-insta`](https://crates.io/crates/cargo-insta)
-//! command can be used to review the snapshots conveniently:
+//! - `new`: writes snapshots for any failing tests into `.snap.new` files,
+//!   pending review
+//! - `always`: writes snapshots for any failing tests into `.snap` files,
+//!   bypassing review
+//! - `unseen`: `always` for previously unseen snapshots or `new` for existing
+//!   snapshots
+//! - `no`: does not write to snapshot files at all; just runs tests
+//!
+//! When `new`, `auto` or `unseen` is used, the
+//! [`cargo-insta`](https://crates.io/crates/cargo-insta) command can be used to
+//! review the snapshots conveniently:
 //!
 //! ```text
 //! $ cargo insta review
 //! ```
 //!
-//! "enter" or "a" accepts a new snapshot, "escape" or "r" rejects,
-//! "space" or "s" skips the snapshot for now.
+//! "enter" or "a" accepts a new snapshot, "escape" or "r" rejects, "space" or
+//! "s" skips the snapshot for now.
 //!
-//! For more information [read the cargo insta docs](https://insta.rs/docs/cli/).
+//! For more information [read the cargo insta
+//! docs](https://insta.rs/docs/cli/).
 //!
 //! # Inline Snapshots
 //!
 //! Additionally snapshots can also be stored inline.  In that case the format
 //! for the snapshot macros is `assert_snapshot!(reference_value, @"snapshot")`.
 //! The leading at sign (`@`) indicates that the following string is the
-//! reference value.  `cargo-insta` will then update that string with the new
-//! value on review.
+//! reference value.  On review, `cargo-insta` will update the string with the
+//! new value.
 //!
 //! Example:
 //!
-#![cfg_attr(feature = "yaml", doc = " ```no_run")]
-#![cfg_attr(not(feature = "yaml"), doc = " ```ignore")]
-//! # use insta::*; use serde::Serialize;
-//! #[derive(Serialize)]
-//! pub struct User {
-//!     username: String,
-//! }
-//!
-//! assert_yaml_snapshot!(User {
-//!     username: "john_doe".to_string(),
-//! }, @"");
+//! ```no_run
+//! # use insta::assert_snapshot;
+//! assert_snapshot!(2 + 2, @"");
 //! ```
 //!
-//! Like with normal snapshots after the initial test failure you can run
-//! `cargo insta review` to accept the change.  The file will then be updated
+//! Like with normal snapshots, an initial test failure will write the proposed
+//! value into a draft file (note that inline snapshots use `.pending-snap`
+//! files rather than `.snap.new` files). Running `cargo insta review` will
+//! review the proposed changes and update the source files on acceptance
 //! automatically.
 //!
 //! # Features
@@ -166,9 +165,9 @@
 //! * `glob`: enables support for globbing ([`glob!`])
 //! * `colors`: enables color output (enabled by default)
 //!
-//! For legacy reasons the `json` and `yaml` features are enabled by default
-//! in limited capacity.  You will receive a deprecation warning if you are
-//! not opting into them but for now the macros will continue to function.
+//! For legacy reasons the `json` and `yaml` features are enabled by default in
+//! limited capacity.  You will receive a deprecation warning if you are not
+//! opting into them but for now the macros will continue to function.
 //!
 //! Enabling any of the serde based formats enables the hidden `serde` feature
 //! which gates some serde specific APIs such as [`Settings::set_info`].
@@ -177,10 +176,10 @@
 //!
 //! `insta` tries to be light in dependencies but this is tricky to accomplish
 //! given what it tries to do.  By default it currently depends on `serde` for
-//! the [`assert_toml_snapshot!`] and [`assert_yaml_snapshot!`] macros.  In
-//! the future this default dependencies will be removed.  To already benefit
-//! from this optimization you can disable the default features and manually
-//! opt into what you want.
+//! the [`assert_toml_snapshot!`] and [`assert_yaml_snapshot!`] macros.  In the
+//! future this default dependencies will be removed.  To already benefit from
+//! this optimization you can disable the default features and manually opt into
+//! what you want.
 //!
 //! # Settings
 //!
@@ -229,10 +228,11 @@
 //!
 //! # Optional: Faster Runs
 //!
-//! Insta benefits from being compiled in release mode, even as dev dependency.  It
-//! will compile slightly slower once, but use less memory, have faster diffs and
-//! just generally be more fun to use.  To achieve that, opt `insta` and `similar`
-//! (the diffing library) into higher optimization in your `Cargo.toml`:
+//! Insta benefits from being compiled in release mode, even as dev dependency.
+//! It will compile slightly slower once, but use less memory, have faster diffs
+//! and just generally be more fun to use.  To achieve that, opt `insta` and
+//! `similar` (the diffing library) into higher optimization in your
+//! `Cargo.toml`:
 //!
 //! ```yaml
 //! [profile.dev.package.insta]

insta/src/runtime.rs

@@ -344,8 +344,7 @@ impl<'a> SnapshotAssertionContext<'a> {
         // let's just make sure there are no more pending files lingering
         // around.
         if let Some(ref snapshot_file) = self.snapshot_file {
-            let mut snapshot_file = snapshot_file.clone();
-            snapshot_file.set_extension("snap.new");
+            let snapshot_file = snapshot_file.clone().with_extension("snap.new");
             fs::remove_file(snapshot_file).ok();
         }
 

insta/src/snapshot.rs

@@ -484,8 +484,7 @@ impl Snapshot {
     /// If the existing snapshot matches the new file, then `None` is returned, otherwise
     /// the name of the new snapshot file.
     pub(crate) fn save_new(&self, path: &Path) -> Result<Option<PathBuf>, Box<dyn Error>> {
-        let mut new_path = path.to_path_buf();
-        new_path.set_extension("snap.new");
+        let new_path = path.to_path_buf().with_extension("snap.new");
         if self.save_with_metadata(&new_path, Some(path), &self.metadata)? {
             Ok(Some(new_path))
         } else {