Document which features turn on what

Cargo.toml

@@ -16,6 +16,7 @@ exclude = [
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 default = ["colors", "legacy_default_serialization"]

Makefile

@@ -4,7 +4,7 @@ build:
 	@cargo build --all-features
 
 doc:
-	@cargo doc --all-features
+	@RUSTC_BOOTSTRAP=1 RUSTDOCFLAGS="--cfg=docsrs" cargo doc --no-deps --all-features
 
 test: cargotest cargo-insta-tests
 

src/filters.rs

@@ -4,6 +4,7 @@ use regex::Regex;
 
 /// Represents stored filters.
 #[derive(Debug, Default, Clone)]
+#[cfg_attr(docsrs, doc(cfg(feature = "filters")))]
 pub struct Filters {
     rules: Vec<(Regex, String)>,
 }

src/lib.rs

@@ -60,19 +60,32 @@
 //!
 //! This crate exports multiple macros for snapshot testing:
 //!
-//! - `assert_snapshot!` for comparing basic string snapshots.
-//! - `assert_debug_snapshot!` for comparing `Debug` outputs of values.
-//! - `assert_display_snapshot!` for comparing `Display` outputs of values.
-//! - `assert_csv_snapshot!` for comparing CSV serialized output of
-//!   types implementing `serde::Serialize`. (requires the `csv` feature)
-//! - `assert_toml_snapshot!` for comparing TOML serialized output of
-//!   types implementing `serde::Serialize`. (requires the `toml` feature)
-//! - `assert_yaml_snapshot!` for comparing YAML serialized
-//!   output of types implementing `serde::Serialize`.
-//! - `assert_ron_snapshot!` for comparing RON serialized output of
-//!   types implementing `serde::Serialize`. (requires the `ron` feature)
-//! - `assert_json_snapshot!` for comparing JSON serialized output of
-//!   types implementing `serde::Serialize`.
+//! - [`assert_snapshot!`] for comparing basic string snapshots.
+//! - [`assert_debug_snapshot!`] for comparing [`Debug`] outputs of values.
+//! - [`assert_display_snapshot!`] for comparing [`Display`](std::fmt::Display) outputs of values.
+//!
+//! The following macros require the use of [`Serialize`](serde::Serialize):
+//!
+#![cfg_attr(
+    feature = "csv",
+    doc = "- [`assert_csv_snapshot!`] for comparing CSV serialized output. (requires the `csv` feature)"
+)]
+#![cfg_attr(
+    feature = "toml",
+    doc = "- [`assert_toml_snapshot!`] for comparing TOML serialized output. (requires the `toml` feature)"
+)]
+#![cfg_attr(
+    feature = "yaml",
+    doc = "- [`assert_yaml_snapshot!`] for comparing YAML serialized output. (requires the `yaml` feature)"
+)]
+#![cfg_attr(
+    feature = "ron",
+    doc = "- [`assert_ron_snapshot!`] for comparing RON serialized output. (requires the `ron` feature)"
+)]
+#![cfg_attr(
+    feature = "json",
+    doc = "- [`assert_json_snapshot!`] for comparing JSON serialized output. (requires the `json` feature)"
+)]
 //!
 //! For macros that work with `serde::Serialize` this crate also permits
 //! redacting of partial values.  See [redactions in the documentation](https://insta.rs/docs/redactions/)
@@ -137,20 +150,35 @@
 //!
 //! The following features exist:
 //!
-//! * `csv`: enables CSV support ([`assert_csv_snapshot!`])
-//! * `json`: enables JSON support ([`assert_json_snapshot!`])
-//! * `ron`: enables RON support ([`assert_ron_snapshot!`])
-//! * `toml`: enables TOML support ([`assert_toml_snapshot!`])
-//! * `yaml`: enables YAML support ([`assert_yaml_snapshot!`])
+//! * `csv`: enables CSV support
+//! * `json`: enables JSON support
+//! * `ron`: enables RON support
+//! * `toml`: enables TOML support
+//! * `yaml`: enables YAML support
 //! * `redactions`: enables support for redactions
 //! * `filters`: enables support for filters
 //! * `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.
+//!
+//! # 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
+//! 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
 //!
 //! There are some settings that can be changed on a per-thread (and thus
 //! per-test) basis.  For more information see [Settings].
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[macro_use]
 mod macros;
 mod content;

src/macros.rs

@@ -35,6 +35,7 @@ macro_rules! _function_name {
 ///
 /// The snapshot name is optional but can be provided as first argument.
 #[cfg(feature = "csv")]
+#[cfg_attr(docsrs, doc(cfg(feature = "csv")))]
 #[macro_export]
 macro_rules! assert_csv_snapshot {
     ($value:expr, @$snapshot:literal) => {{
@@ -78,6 +79,7 @@ macro_rules! assert_csv_snapshot {
 ///
 /// The snapshot name is optional but can be provided as first argument.
 #[cfg(feature = "toml")]
+#[cfg_attr(docsrs, doc(cfg(feature = "toml")))]
 #[macro_export]
 macro_rules! assert_toml_snapshot {
     ($value:expr, @$snapshot:literal) => {{
@@ -148,6 +150,7 @@ macro_rules! assert_toml_snapshot {
     deprecated(note = "assert_yaml_snapshot! will require the \"yaml\" feature. \
         Add the \"yaml\" feature to your Cargo.toml to silence this warning.")
 )]
+#[cfg_attr(docsrs, doc(cfg(feature = "yaml")))]
 #[macro_export]
 macro_rules! assert_yaml_snapshot {
     ($value:expr, @$snapshot:literal) => {{
@@ -191,6 +194,7 @@ macro_rules! assert_yaml_snapshot {
 ///
 /// The snapshot name is optional but can be provided as first argument.
 #[cfg(feature = "ron")]
+#[cfg_attr(docsrs, doc(cfg(feature = "ron")))]
 #[macro_export]
 macro_rules! assert_ron_snapshot {
     ($value:expr, @$snapshot:literal) => {{
@@ -237,6 +241,7 @@ macro_rules! assert_ron_snapshot {
     deprecated(note = "assert_json_snapshot! will require the \"json\" feature. \
         Add the \"json\" feature to your Cargo.toml to silence this warning.")
 )]
+#[cfg_attr(docsrs, doc(cfg(feature = "json")))]
 #[macro_export]
 macro_rules! assert_json_snapshot {
     ($value:expr, @$snapshot:literal) => {{
@@ -470,6 +475,7 @@ macro_rules! with_settings {
 ///
 /// The closure is passed the path to the file.
 #[cfg(feature = "glob")]
+#[cfg_attr(docsrs, doc(cfg(feature = "glob")))]
 #[macro_export]
 macro_rules! glob {
     ($glob:expr, $closure:expr) => {{

src/redaction.rs

@@ -23,6 +23,7 @@ impl SelectorParseError {
 /// This can be converted into a string with `to_string` to see a stringified
 /// path that the selector matched.
 #[derive(Clone, Debug)]
+#[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
 pub struct ContentPath<'a>(&'a [PathItem]);
 
 impl<'a> fmt::Display for ContentPath<'a> {
@@ -48,6 +49,7 @@ impl<'a> fmt::Display for ContentPath<'a> {
 /// Replaces a value with another one.
 
 /// Represents a redaction.
+#[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
 pub enum Redaction {
     /// Static redaction with new content.
     Static(Content),
@@ -121,6 +123,7 @@ impl<'a> From<&'a [u8]> for Redaction {
 ///     "[uuid]"
 /// }));
 /// ```
+#[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
 pub fn dynamic_redaction<I, F>(func: F) -> Redaction
 where
     I: Into<Content>,
@@ -142,6 +145,7 @@ where
 /// # let mut settings = Settings::new();
 /// settings.add_redaction(".flags", sorted_redaction());
 /// ```
+#[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
 pub fn sorted_redaction() -> Redaction {
     fn sort(mut value: Content, _path: ContentPath) -> Content {
         match value.resolve_inner_mut() {

src/settings.rs

@@ -40,6 +40,7 @@ thread_local!(static CURRENT_SETTINGS: RefCell<Settings> = RefCell::new(Settings
 
 /// Represents stored redactions.
 #[cfg(feature = "redactions")]
+#[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
 #[derive(Clone, Default)]
 pub struct Redactions(Vec<(Selector<'static>, Arc<Redaction>)>);
 
@@ -365,6 +366,7 @@ impl Settings {
     /// Note that this only applies to snapshots that undergo serialization
     /// (eg: does not work for `assert_debug_snapshot!`.)
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub fn add_redaction<R: Into<Redaction>>(&mut self, selector: &str, replacement: R) {
         self._private_inner_mut().redactions.0.push((
             Selector::parse(selector).unwrap().make_static(),
@@ -380,6 +382,7 @@ impl Settings {
     ///
     /// This is a shortcut to `add_redaction(selector, dynamic_redaction(...))`;
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub fn add_dynamic_redaction<I, F>(&mut self, selector: &str, func: F)
     where
         I: Into<Content>,
@@ -392,6 +395,7 @@ impl Settings {
     ///
     /// This is a shortcut to `add_redaction(selector, sorted_redaction())`.
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub fn sort_selector(&mut self, selector: &str) {
         self.add_redaction(selector, sorted_redaction());
     }
@@ -400,18 +404,21 @@ impl Settings {
     ///
     /// The default set is empty.
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub fn set_redactions<R: Into<Redactions>>(&mut self, redactions: R) {
         self._private_inner_mut().redactions(redactions);
     }
 
     /// Removes all redactions.
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub fn clear_redactions(&mut self) {
         self._private_inner_mut().redactions.0.clear();
     }
 
     /// Iterate over the redactions.
     #[cfg(feature = "redactions")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "redactions")))]
     pub(crate) fn iter_redactions(&self) -> impl Iterator<Item = (&Selector, &Redaction)> {
         self.inner
             .redactions
@@ -440,6 +447,7 @@ impl Settings {
     /// # }
     /// ```
     #[cfg(feature = "filters")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "filters")))]
     pub fn add_filter<S: Into<String>>(&mut self, regex: &str, replacement: S) {
         self._private_inner_mut().filters.add(regex, replacement);
     }
@@ -448,18 +456,21 @@ impl Settings {
     ///
     /// The default set is empty.
     #[cfg(feature = "filters")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "filters")))]
     pub fn set_filters<F: Into<Filters>>(&mut self, filters: F) {
         self._private_inner_mut().filters(filters);
     }
 
     /// Removes all filters.
     #[cfg(feature = "filters")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "filters")))]
     pub fn clear_filters(&mut self) {
         self._private_inner_mut().filters.clear();
     }
 
     /// Returns the current filters
     #[cfg(feature = "filters")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "filters")))]
     pub(crate) fn filters(&self) -> &Filters {
         &self.inner.filters
     }