Add some docstrings & a couple of renamings

cargo-insta/src/cli.rs

@@ -1041,7 +1041,7 @@ fn pending_snapshots_cmd(cmd: PendingSnapshotsCommand) -> Result<(), Box<dyn Err
     #[derive(Serialize, Debug)]
     #[serde(rename_all = "snake_case", tag = "type")]
     enum SnapshotKey<'a> {
-        NamedSnapshot {
+        FileSnapshot {
             path: &'a Path,
         },
         InlineSnapshot {
@@ -1070,7 +1070,7 @@ fn pending_snapshots_cmd(cmd: PendingSnapshotsCommand) -> Result<(), Box<dyn Err
                         expression: snapshot_ref.new.metadata().expression(),
                     }
                 } else {
-                    SnapshotKey::NamedSnapshot { path: &target_file }
+                    SnapshotKey::FileSnapshot { path: &target_file }
                 };
                 println!("{}", serde_json::to_string(&info).unwrap());
             } else if is_inline {

cargo-insta/src/container.rs

@@ -47,6 +47,9 @@ impl PendingSnapshot {
     }
 }
 
+/// A snapshot and its context, which allows us to save the snapshot. It holds
+/// either a single file snapshot, or all the inline snapshots from a single
+/// rust file.
 #[derive(Debug)]
 pub(crate) struct SnapshotContainer {
     snapshot_path: PathBuf,

insta/src/runtime.rs

@@ -49,38 +49,38 @@ pub struct AutoName;
 
 impl From<AutoName> for ReferenceValue<'static> {
     fn from(_value: AutoName) -> ReferenceValue<'static> {
-        ReferenceValue::Named(None)
+        ReferenceValue::File(None)
     }
 }
 
 impl From<Option<String>> for ReferenceValue<'static> {
     fn from(value: Option<String>) -> ReferenceValue<'static> {
-        ReferenceValue::Named(value.map(Cow::Owned))
+        ReferenceValue::File(value.map(Cow::Owned))
     }
 }
 
 impl From<String> for ReferenceValue<'static> {
     fn from(value: String) -> ReferenceValue<'static> {
-        ReferenceValue::Named(Some(Cow::Owned(value)))
+        ReferenceValue::File(Some(Cow::Owned(value)))
     }
 }
 
 impl<'a> From<Option<&'a str>> for ReferenceValue<'a> {
     fn from(value: Option<&'a str>) -> ReferenceValue<'a> {
-        ReferenceValue::Named(value.map(Cow::Borrowed))
+        ReferenceValue::File(value.map(Cow::Borrowed))
     }
 }
 
 impl<'a> From<&'a str> for ReferenceValue<'a> {
     fn from(value: &'a str) -> ReferenceValue<'a> {
-        ReferenceValue::Named(Some(Cow::Borrowed(value)))
+        ReferenceValue::File(Some(Cow::Borrowed(value)))
     }
 }
 
 /// A reference to a snapshot
 pub enum ReferenceValue<'a> {
-    /// A named snapshot, where the inner value is the snapshot name.
-    Named(Option<Cow<'a, str>>),
+    /// A file snapshot, where the inner value is the snapshot name.
+    File(Option<Cow<'a, str>>),
     /// An inline snapshot, where the inner value is the snapshot contents.
     Inline(&'a str),
 }
@@ -197,6 +197,8 @@ fn get_snapshot_filename(
     })
 }
 
+/// A single snapshot including surrounding context which allows us to assert
+/// and save the snapshot.
 #[derive(Debug)]
 struct SnapshotAssertionContext<'a> {
     tool_config: Arc<ToolConfig>,
@@ -231,7 +233,7 @@ impl<'a> SnapshotAssertionContext<'a> {
         let is_doctest = is_doctest(function_name);
 
         match refval {
-            ReferenceValue::Named(name) => {
+            ReferenceValue::File(name) => {
                 let name = match name {
                     Some(name) => add_suffix_to_snapshot_name(name),
                     None => {

insta/src/snapshot.rs

@@ -19,6 +19,8 @@ lazy_static::lazy_static! {
     };
 }
 
+/// Holds a pending inline snapshot loaded from a json file or read from an assert
+/// macro (doesn't write to the rust file, which is done by `cargo-insta`)
 #[derive(Debug)]
 pub struct PendingInlineSnapshot {
     pub run_id: String,