diff --git a/cargo-insta/src/main.rs b/cargo-insta/src/main.rs index 033b5706..487b35a5 100644 --- a/cargo-insta/src/main.rs +++ b/cargo-insta/src/main.rs @@ -1,3 +1,6 @@ +#![warn(clippy::doc_markdown)] +#![warn(rustdoc::all)] + //!
//! //!

cargo-insta: review tool for insta, a snapshot testing library for Rust

diff --git a/cargo-insta/tests/main.rs b/cargo-insta/tests/main.rs index ee890a72..97ce5c44 100644 --- a/cargo-insta/tests/main.rs +++ b/cargo-insta/tests/main.rs @@ -60,7 +60,7 @@ impl TestFiles { } } -/// Path of the insta crate in this repo, which we use as a dependency in the test project +/// Path of the [`insta`] crate in this repo, which we use as a dependency in the test project fn insta_path() -> PathBuf { PathBuf::from(env!("CARGO_MANIFEST_DIR")) .parent() diff --git a/insta/src/content/json.rs b/insta/src/content/json.rs index 2141226a..e4dd5e67 100644 --- a/insta/src/content/json.rs +++ b/insta/src/content/json.rs @@ -29,7 +29,7 @@ pub struct Serializer { } impl Serializer { - /// Creates a new serializer that writes into the given writer. + /// Creates a new [`Serializer`] that writes into the given writer. pub fn new() -> Serializer { Serializer { out: String::new(), diff --git a/insta/src/content/mod.rs b/insta/src/content/mod.rs index 435e922c..dc3210ed 100644 --- a/insta/src/content/mod.rs +++ b/insta/src/content/mod.rs @@ -55,7 +55,7 @@ impl std::error::Error for Error {} /// /// Some enum variants are intentionally not exposed to user code. /// It's generally recommended to construct content objects by -/// using the [`From`](std::convert::From) trait and by using the +/// using the [`From`] trait and by using the /// accessor methods to assert on it. /// /// While matching on the content is possible in theory it is @@ -63,12 +63,12 @@ impl std::error::Error for Error {} /// enum holds variants that can "wrap" values where it's not /// expected. For instance if a field holds an `Option` /// you cannot use pattern matching to extract the string as it -/// will be contained in an internal `Some` variant that is not -/// exposed. On the other hand the `as_str` method will +/// will be contained in an internal [`Some`] variant that is not +/// exposed. On the other hand the [`Content::as_str`] method will /// automatically resolve such internal wrappers. /// /// If you do need to pattern match you should use the -/// `resolve_inner` method to resolve such internal wrappers. +/// [`Content::resolve_inner`] method to resolve such internal wrappers. #[derive(Debug, Clone, PartialEq, PartialOrd)] pub enum Content { Bool(bool), @@ -194,7 +194,7 @@ impl Content { } } - /// Mutable version of [`resolve_inner`](Self::resolve_inner). + /// Mutable version of [`Self::resolve_inner`]. pub fn resolve_inner_mut(&mut self) -> &mut Content { match *self { Content::Some(ref mut v) diff --git a/insta/src/content/serialization.rs b/insta/src/content/serialization.rs index b0eeea6d..e9223e2a 100644 --- a/insta/src/content/serialization.rs +++ b/insta/src/content/serialization.rs @@ -19,7 +19,7 @@ pub enum Key<'a> { } impl<'a> Key<'a> { - /// Needed because std::mem::discriminant is not Ord + /// Needed because [`std::mem::discriminant`] is not [`Ord`] fn discriminant(&self) -> usize { match self { Key::Bool(_) => 1, diff --git a/insta/src/content/yaml/vendored/emitter.rs b/insta/src/content/yaml/vendored/emitter.rs index 7c8260f8..2ea1f2c2 100644 --- a/insta/src/content/yaml/vendored/emitter.rs +++ b/insta/src/content/yaml/vendored/emitter.rs @@ -38,7 +38,7 @@ pub struct YamlEmitter<'a> { pub type EmitResult = Result<(), EmitError>; -// from serialize::json +/// From [`serialize::json`] fn escape_str(wr: &mut dyn fmt::Write, v: &str) -> Result<(), fmt::Error> { wr.write_str("\"")?; @@ -248,12 +248,13 @@ impl<'a> YamlEmitter<'a> { } } +#[allow(clippy::doc_markdown)] // \` is recognised as unbalanced backticks /// Check if the string requires quoting. /// /// Strings starting with any of the following characters must be quoted. /// `:`, `&`, `*`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@` /// Strings containing any of the following characters must be quoted. -/// `{`, `}`, `[`, `]`, `,`, `#`, `\`` +/// `{`, `}`, `\[`, `\]`, `,`, `#`, `\`` /// /// If the string contains any of the following control characters, it must be escaped with double quotes: /// `\0`, `\x01`, `\x02`, `\x03`, `\x04`, `\x05`, `\x06`, `\a`, `\b`, `\t`, `\n, `\v, `\f`, `\r`, `\x0e`, `\x0f`, `\x10`, `\x11`, `\x12`, `\x13`, `\x14`, `\x15`, `\x16`, `\x17`, `\x18`, `\x19`, `\x1a`, `\e`, `\x1c`, `\x1d`, `\x1e`, `\x1f`, `\N`, `\_`, `\L`, `\P` diff --git a/insta/src/content/yaml/vendored/parser.rs b/insta/src/content/yaml/vendored/parser.rs index 1656bba9..b21ecb07 100644 --- a/insta/src/content/yaml/vendored/parser.rs +++ b/insta/src/content/yaml/vendored/parser.rs @@ -29,8 +29,8 @@ enum State { End, } -/// `Event` is used with the low-level event base parsing API, -/// see `EventReceiver` trait. +/// [`Event`] is used with the low-level event base parsing API, +/// see [`EventReceiver`] trait. #[derive(Clone, PartialEq, Debug, Eq)] pub enum Event { /// Reserved for internal use @@ -40,7 +40,7 @@ pub enum Event { DocumentEnd, /// Refer to an anchor ID Alias(usize), - /// Value, style, anchor_id, tag + /// Value, style, anchor ID, tag Scalar(String, TScalarStyle, usize, Option), /// Anchor ID SequenceStart(usize), diff --git a/insta/src/content/yaml/vendored/yaml.rs b/insta/src/content/yaml/vendored/yaml.rs index df502b2b..96787f76 100644 --- a/insta/src/content/yaml/vendored/yaml.rs +++ b/insta/src/content/yaml/vendored/yaml.rs @@ -14,8 +14,8 @@ use std::vec; /// access your YAML document. #[derive(Clone, PartialEq, PartialOrd, Debug, Eq, Ord, Hash)] pub enum Yaml { - /// Float types are stored as String and parsed on demand. - /// Note that f64 does NOT implement Eq trait and can NOT be stored in BTreeMap. + /// Float types are stored as [`String`] and parsed on demand. + /// Note that [`f64'] does NOT implement [`Eq'] trait and can NOT be stored in [`BTreeMap`]. Real(string::String), /// YAML int is stored as i64. Integer(i64), diff --git a/insta/src/env.rs b/insta/src/env.rs index 63ea8c4e..14f02b93 100644 --- a/insta/src/env.rs +++ b/insta/src/env.rs @@ -321,7 +321,7 @@ impl ToolConfig { self.snapshot_update } - /// Returns the value of glob_fail_fast + /// Returns whether the glob should fail fast, as snapshot failures within the glob macro will appear only at the end of execution unless `glob_fail_fast` is set. #[cfg(feature = "glob")] pub fn glob_fail_fast(&self) -> bool { self.glob_fail_fast diff --git a/insta/src/lib.rs b/insta/src/lib.rs index 9c1fc81b..b6b13ee7 100644 --- a/insta/src/lib.rs +++ b/insta/src/lib.rs @@ -1,3 +1,6 @@ +#![warn(clippy::doc_markdown)] +#![warn(rustdoc::all)] + //!
//! //!

insta: a snapshot testing library for Rust

@@ -7,7 +10,7 @@ //! //! Snapshots tests (also sometimes called approval tests) are tests that //! assert values against a reference value (the snapshot). This is similar -//! to how `assert_eq!` lets you compare a value against a reference value but +//! to how [`assert_eq!`] lets you compare a value against a reference value but //! unlike simple string assertions, snapshot tests let you test against complex //! values and come with comprehensive tools to review changes. //! @@ -81,7 +84,7 @@ //! [`Display`](std::fmt::Display) outputs, often strings. //! - [`assert_debug_snapshot!`] for comparing [`Debug`] outputs of values. //! -//! The following macros require the use of serde's [`Serialize`](serde::Serialize): +//! The following macros require the use of [`serde::Serialize`]: //! #![cfg_attr( feature = "csv", @@ -171,11 +174,11 @@ //! //! The following features exist: //! -//! * `csv`: enables CSV support (via serde) -//! * `json`: enables JSON support (via serde) -//! * `ron`: enables RON support (via serde) -//! * `toml`: enables TOML support (via serde) -//! * `yaml`: enables YAML support (via serde) +//! * `csv`: enables CSV support (via [`serde`]) +//! * `json`: enables JSON support (via [`serde`]) +//! * `ron`: enables RON support (via [`serde`]) +//! * `toml`: enables TOML support (via [`serde`]) +//! * `yaml`: enables YAML support (via [`serde`]) //! * `redactions`: enables support for redactions //! * `filters`: enables support for filters //! * `glob`: enables support for globbing ([`glob!`]) @@ -185,13 +188,14 @@ //! 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`]. +//! Enabling any of the [`serde`] based formats enables the hidden `serde` feature +//! which gates some [`serde`] specific APIs such as [`Settings::set_info`]. //! //! # Dependencies //! -//! `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 +//! [`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 @@ -202,7 +206,7 @@ //! There are some settings that can be changed on a per-thread (and thus //! per-test) basis. For more information see [Settings]. //! -//! Additionally Insta will load a YAML config file with settings that change +//! Additionally, Insta will load a YAML config file with settings that change //! the behavior of insta between runs. It's loaded from any of the following //! locations: `.config/insta.yaml`, `insta.yaml` and `.insta.yaml` from the //! workspace root. The following config options exist: @@ -247,8 +251,8 @@ //! //! 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 +//! 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 @@ -259,8 +263,10 @@ //! opt-level = 3 //! ``` //! -//! You can also disable the default features of `insta` which will cut down on +//! You can also disable the default features of [`insta`] which will cut down on //! the compile time a bit by removing some quality of life features. +//! +//! [`insta`]: https://docs.rs/insta #![cfg_attr(docsrs, feature(doc_cfg))] #[macro_use] diff --git a/insta/src/macros.rs b/insta/src/macros.rs index 6c1ce27a..aebc832d 100644 --- a/insta/src/macros.rs +++ b/insta/src/macros.rs @@ -28,11 +28,11 @@ macro_rules! _get_workspace_root { }}; } -/// Asserts a `Serialize` snapshot in CSV format. +/// Asserts a [`serde::Serialize`] snapshot in CSV format. /// /// **Feature:** `csv` (disabled by default) /// -/// This works exactly like [`crate::assert_yaml_snapshot!`] +/// This works exactly like [`assert_yaml_snapshot!`](crate::assert_yaml_snapshot!) /// but serializes in [CSV](https://github.com/burntsushi/rust-csv) format instead of /// YAML. /// @@ -57,11 +57,11 @@ macro_rules! assert_csv_snapshot { }; } -/// Asserts a `Serialize` snapshot in TOML format. +/// Asserts a [`serde::Serialize`] snapshot in TOML format. /// /// **Feature:** `toml` (disabled by default) /// -/// This works exactly like [`crate::assert_yaml_snapshot!`] +/// This works exactly like [`assert_yaml_snapshot!`](crate::assert_yaml_snapshot!) /// but serializes in [TOML](https://github.com/alexcrichton/toml-rs) format instead of /// YAML. Note that TOML cannot represent all values due to limitations in the /// format. @@ -87,14 +87,14 @@ macro_rules! assert_toml_snapshot { }; } -/// Asserts a `Serialize` snapshot in YAML format. +/// Asserts a [`serde::Serialize`] snapshot in YAML format. /// /// **Feature:** `yaml` /// -/// The value needs to implement the `serde::Serialize` trait and the snapshot +/// The value needs to implement the [`serde::Serialize`] trait and the snapshot /// will be serialized in YAML format. This does mean that unlike the debug /// snapshot variant the type of the value does not appear in the output. -/// You can however use the `assert_ron_snapshot!` macro to dump out +/// You can however use the [`assert_ron_snapshot!`](crate::assert_ron_snapshot!) macro to dump out /// the value in [RON](https://github.com/ron-rs/ron/) format which retains some /// type information for more accurate comparisons. /// @@ -105,7 +105,7 @@ macro_rules! assert_toml_snapshot { /// assert_yaml_snapshot!(vec![1, 2, 3]); /// ``` /// -/// Unlike the [`crate::assert_debug_snapshot!`] +/// Unlike the [`assert_debug_snapshot!`](crate::assert_debug_snapshot!) /// macro, this one has a secondary mode where redactions can be defined. /// /// The third argument to the macro can be an object expression for redaction. @@ -141,11 +141,11 @@ macro_rules! assert_yaml_snapshot { }; } -/// Asserts a `Serialize` snapshot in RON format. +/// Asserts a [`serde::Serialize`] snapshot in RON format. /// /// **Feature:** `ron` (disabled by default) /// -/// This works exactly like [`assert_yaml_snapshot!`] +/// This works exactly like [`assert_yaml_snapshot!`](crate::assert_yaml_snapshot!) /// but serializes in [RON](https://github.com/ron-rs/ron/) format instead of /// YAML which retains some type information for more accurate comparisons. /// @@ -171,11 +171,11 @@ macro_rules! assert_ron_snapshot { }; } -/// Asserts a `Serialize` snapshot in JSON format. +/// Asserts a [`serde::Serialize`] snapshot in JSON format. /// /// **Feature:** `json` /// -/// This works exactly like [`assert_yaml_snapshot!`] but serializes in JSON format. +/// This works exactly like [`assert_yaml_snapshot!`](crate::assert_yaml_snapshot!) but serializes in JSON format. /// This is normally not recommended because it makes diffs less reliable, but it can /// be useful for certain specialized situations. /// @@ -201,11 +201,11 @@ macro_rules! assert_json_snapshot { }; } -/// Asserts a `Serialize` snapshot in compact JSON format. +/// Asserts a [`serde::Serialize`] snapshot in compact JSON format. /// /// **Feature:** `json` /// -/// This works exactly like [`assert_json_snapshot!`] but serializes into a single +/// This works exactly like [`assert_json_snapshot!`](crate::assert_json_snapshot!) but serializes into a single /// line for as long as the output is less than 120 characters. This can be useful /// in cases where you are working with small result outputs but comes at the cost /// of slightly worse diffing behavior. @@ -297,10 +297,10 @@ macro_rules! _prepare_snapshot_for_redaction { }; } -/// Asserts a `Debug` snapshot. +/// Asserts a [`Debug`] snapshot. /// -/// The value needs to implement the `fmt::Debug` trait. This is useful for -/// simple values that do not implement the `Serialize` trait, but does not +/// The value needs to implement the [`Debug`] trait. This is useful for +/// simple values that do not implement the [`serde::Serialize`] trait, but does not /// permit redactions. /// /// Debug is called with `"{:#?}"`, which means this uses pretty-print. @@ -311,10 +311,10 @@ macro_rules! assert_debug_snapshot { }; } -/// Asserts a `Debug` snapshot in compact format. +/// Asserts a [`Debug`] snapshot in compact format. /// -/// The value needs to implement the `fmt::Debug` trait. This is useful for -/// simple values that do not implement the `Serialize` trait, but does not +/// The value needs to implement the [`Debug`] trait. This is useful for +/// simple values that do not implement the [`serde::Serialize`] trait, but does not /// permit redactions. /// /// Debug is called with `"{:?}"`, which means this does not use pretty-print. @@ -411,9 +411,9 @@ macro_rules! assert_binary_snapshot { }; } -/// Asserts a `Display` snapshot. +/// Asserts a [`Display`](std::fmt::Display) snapshot. /// -/// This is now deprecated, replaced by the more generic `assert_snapshot!()` +/// This is now deprecated, replaced by the more generic [`assert_snapshot!`](crate::assert_snapshot!) #[macro_export] #[deprecated = "use assert_snapshot!() instead"] macro_rules! assert_display_snapshot { @@ -422,10 +422,10 @@ macro_rules! assert_display_snapshot { }; } -/// Asserts a string snapshot. +/// Asserts a [`String`] snapshot. /// -/// This is the simplest of all assertion methods. It accepts any value that -/// implements `fmt::Display`. +/// This is the simplest of all assertion methods. +/// It accepts any value that implements [`Display`](std::fmt::Display). /// /// ```no_run /// # use insta::*; diff --git a/insta/src/redaction.rs b/insta/src/redaction.rs index 525b3294..423e7fec 100644 --- a/insta/src/redaction.rs +++ b/insta/src/redaction.rs @@ -136,7 +136,7 @@ where /// /// This is useful to force something like a set or map to be ordered to make /// it deterministic. This is necessary as insta's serialization support is -/// based on serde which does not have native set support. As a result vectors +/// based on [`serde`] which does not have native set support. As a result vectors /// (which need to retain order) and sets (which should be given a stable order) /// look the same. /// diff --git a/insta/src/runtime.rs b/insta/src/runtime.rs index 088f8ab2..df64e5b6 100644 --- a/insta/src/runtime.rs +++ b/insta/src/runtime.rs @@ -804,6 +804,7 @@ pub fn assert_snapshot( Ok(()) } +#[allow(rustdoc::private_doc_tests)] /// Test snapshots in doctests. /// /// ``` diff --git a/insta/src/settings.rs b/insta/src/settings.rs index 74048818..1a1f4425 100644 --- a/insta/src/settings.rs +++ b/insta/src/settings.rs @@ -176,7 +176,7 @@ impl Default for Settings { impl Settings { /// Returns the default settings. /// - /// It's recommended to use `clone_current` instead so that + /// It's recommended to use [`Self::clone_current`] instead so that /// already applied modifications are not discarded. pub fn new() -> Settings { Settings::default() @@ -196,7 +196,7 @@ impl Settings { /// Enables forceful sorting of maps before serialization. /// /// Note that this only applies to snapshots that undergo serialization - /// (eg: does not work for `assert_debug_snapshot!`.) + /// (eg: does not work for [`assert_debug_snapshot!`](crate::assert_debug_snapshot!).) /// /// The default value is `false`. pub fn set_sort_maps(&mut self, value: bool) { @@ -295,7 +295,7 @@ impl Settings { /// super useful by itself, particularly when working with loops and generated /// tests. In that case the `description` can be set as extra information. /// - /// See also [`set_info`](Self::set_info). + /// See also [`Self::set_info`]. pub fn set_description>(&mut self, value: S) { self._private_inner_mut().description(value); } @@ -320,7 +320,7 @@ impl Settings { /// As an example the input parameters to the function that creates the snapshot /// can be persisted here. /// - /// Alternatively you can use [`set_raw_info`](Self::set_raw_info) instead. + /// Alternatively you can use [`Self::set_raw_info`] instead. #[cfg(feature = "serde")] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] pub fn set_info(&mut self, s: &S) { @@ -329,7 +329,7 @@ impl Settings { /// Sets the info from a content object. /// - /// This works like [`set_info`](Self::set_info) but does not require `serde`. + /// This works like [`Self::set_info`] but does not require [`serde`]. pub fn set_raw_info(&mut self, content: &Content) { self._private_inner_mut().raw_info(content); } @@ -365,7 +365,7 @@ impl Settings { /// snapshots. /// /// Note that this only applies to snapshots that undergo serialization - /// (eg: does not work for `assert_debug_snapshot!`.) + /// (eg: does not work for [`assert_debug_snapshot!`](crate::assert_debug_snapshot!).) #[cfg(feature = "redactions")] #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))] pub fn add_redaction>(&mut self, selector: &str, replacement: R) { @@ -384,7 +384,7 @@ impl Settings { /// /// This works similar to a redaction but instead of changing the value it /// asserts the value at a certain place. This function is internally - /// supposed to call things like `assert_eq!`. + /// supposed to call things like [`assert_eq!`]. /// /// This is a shortcut to `add_redaction(selector, dynamic_redaction(...))`; #[cfg(feature = "redactions")] @@ -437,7 +437,7 @@ impl Settings { /// /// The first argument is the [`regex`] pattern to apply, the second is a replacement /// string. The replacement string has the same functionality as the second argument - /// to [`Regex::replace`](regex::Regex::replace). + /// to [`regex::Regex::replace`]. /// /// This is useful to perform some cleanup procedures on the snapshot for unstable values. /// @@ -493,7 +493,7 @@ impl Settings { /// Runs a function with the current settings bound to the thread. /// - /// This is an alternative to [`bind_to_scope`](Settings::bind_to_scope) + /// This is an alternative to [`Self::bind_to_scope`]() /// which does not require holding on to a drop guard. The return value /// of the closure is passed through. /// @@ -510,7 +510,7 @@ impl Settings { f() } - /// Like `bind` but for futures. + /// Like [`Self::bind`] but for futures. /// /// This lets you bind settings for the duration of a future like this: /// @@ -579,7 +579,7 @@ impl Settings { } } -/// Returned from [`bind_to_scope`](Settings::bind_to_scope) +/// Returned from [`Settings::bind_to_scope`] #[must_use = "The guard is immediately dropped so binding has no effect. Use `let _guard = ...` to bind it."] pub struct SettingsBindDropGuard(Option>); diff --git a/insta/src/snapshot.rs b/insta/src/snapshot.rs index 21d3a889..9ec42644 100644 --- a/insta/src/snapshot.rs +++ b/insta/src/snapshot.rs @@ -598,7 +598,7 @@ impl Snapshot { self.save_with_metadata(path, &self.metadata.trim_for_persistence()) } - /// Same as `save` but instead of writing a normal snapshot file this will write + /// Same as [`Self::save`] but instead of writing a normal snapshot file this will write /// a `.snap.new` file with additional information. /// /// The name of the new snapshot file is returned. diff --git a/insta/tests/test_inline.rs b/insta/tests/test_inline.rs index bdee1fed..fe936908 100644 --- a/insta/tests/test_inline.rs +++ b/insta/tests/test_inline.rs @@ -61,6 +61,11 @@ fn test_newline() { "###); } +#[test] +fn test_inline_debug_expr() { + assert_snapshot!("hello", "a debug expr", @"hello"); +} + #[cfg(feature = "csv")] #[test] fn test_csv_inline() {