docs: improved the linking inside and outside of the crate (#618)

While browsing the docs on docs.rs, I noticed that there are a few items
which are not linked.
This PR tries to improve this situation.

Drawing attention to one thing which might be controversial:
In the current codebase, the usage of `[´foo´](Self::foo)` and
`[´Self::foo´]` (and related links) are a bit inconsistent. I have
changed all to the `[´Self::foo´]` format. Please let me know if you
prefer the first and I can change them to that format.

I have verified this change via adding the following (somewhat
agressive) docs-related lints and running `RUSTDOCFLAGS="--cfg=docsrs"
cargo +nightly doc --no-deps --all-features` and `cargo clippy
--all-features --all`.

```rust
#![warn(clippy::doc_markdown)]
#![warn(rustdoc::all)]
```

---------

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

cargo-insta/src/main.rs

@@ -1,3 +1,6 @@
+#![warn(clippy::doc_markdown)]
+#![warn(rustdoc::all)]
+
 //! <div align="center">
 //!  <img src="https://github.com/mitsuhiko/insta/blob/master/assets/logo.png?raw=true" width="250" height="250">
 //!  <p><strong>cargo-insta: review tool for insta, a snapshot testing library for Rust</strong></p>

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()

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(),

insta/src/content/mod.rs

@@ -57,20 +57,20 @@ 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
 /// recommended against.  The reason for this is that the content
 /// enum holds variants that can "wrap" values where it's not
 /// expected.  For instance if a field holds an `Option<String>`
 /// 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),
@@ -196,7 +196,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)

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,

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`

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<TokenType>),
     /// Anchor ID
     SequenceStart(usize),

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),

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

insta/src/lib.rs

@@ -1,3 +1,6 @@
+#![warn(clippy::doc_markdown)]
+#![warn(rustdoc::all)]
+
 //! <div align="center">
 //!  <img src="https://github.com/mitsuhiko/insta/blob/master/assets/logo.png?raw=true" width="250" height="250">
 //!  <p><strong>insta: a snapshot testing library for Rust</strong></p>
@@ -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]

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.
@@ -373,9 +373,9 @@ macro_rules! _assert_snapshot_base {
     };
 }
 
-/// 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 {
@@ -384,10 +384,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::*;

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.
 ///

insta/src/runtime.rs

@@ -701,6 +701,7 @@ pub fn assert_snapshot(
     Ok(())
 }
 
+#[allow(rustdoc::private_doc_tests)]
 /// Test snapshots in doctests.
 ///
 /// ```