Improve docs around unknown_variants{,_slim} features

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "scryfall"
-version = "0.17.5"
+version = "0.17.7"
 authors = ["Mendess2526 <[email protected]>"]
 edition = "2021"
 description = "A wrapper around the scryfall magic the gathering api"
@@ -10,9 +10,12 @@ readme = "README.md"
 keywords = ["mtg", "Magic", "API", "Scryfall"]
 categories = ["api-bindings", "games"]
 
+[package.metadata.docs.rs]
+features = ["unknown_variants"]
+
 [features]
 default = ["bulk_caching"]
-bulk_caching = ["heck"]
+bulk_caching = ["dep:heck"]
 unknown_variants = []
 unknown_variants_slim = []
 bin = ["dep:tokio"]

README.md

@@ -42,13 +42,13 @@ assert_eq!(Set::code("mmq").unwrap().name, "Mercadian Masques")
 Scryfall makes a lot of breaking api changes, mostly because magic makes a lot
 of breaking changes 😅. Due to the strong typing of this crate, this means that
 sometimes code that works one day breaks the next day. For example, there's a
-[Format](./src/format.rs) enum. This enum, when deserializing, will strictly
+[`Format`][format-enum] enum. This enum, when deserializing, will strictly
 reject any format it doesn't know about. This means that everytime wizards adds
-a new format, this scryfall will start returning this new format from its API
+a new format, scryfall will start returning this new format from its API
 which will make your code fail at runtime.
 
 To cope with this I've added a feature called `unknown_variants`. This feature
-adds to these troublesome enums a variant called `Unknown`, which contains the
+adds to these troublesome enums a variant called [`Unknown`][format-unknown], which contains the
 string representation of the unknown format.
 
 This has a few pros and cons:
@@ -63,10 +63,10 @@ This has a few pros and cons:
       when the new variant is added to the enum, it will stop showing up in the
       unknown variant. For example, if tomorrow wizards adds a format called
       "Frontier" and you have `unknown_variants` enabled, `"frontier"` will
-      start showing up inside the `Format::Unknown` variant. But in the next
+      start showing up inside the [`Format::Unknown`][format-unknown] variant. But in the next
       version of this crate, I will add `Format::Frontier`, which means that if
       you upgrade your dependency on this crate, `"frontier"` will no longer
-      show up inside the `Format::Unknown` variant. If you depend on that
+      show up inside the [`Format::Unknown`][format-unknown] variant. If you depend on that
       behaviour it will be considered a breaking change.
 
 If you want to have the unknown variant but don't want to pay for the 16 byte
@@ -75,3 +75,6 @@ an empty `Unknown` variant instead.
 
 These two features are incompatible and `unknown_variants` will take
 precedence if both are present.
+
+[format-enum]: https://docs.rs/scryfall/latest/scryfall/format/enum.Format.html
+[format-unknown]: https://docs.rs/scryfall/latest/scryfall/format/enum.Format.html#variant.Unknown

src/card/finishes.rs

@@ -19,10 +19,20 @@ pub enum Finishes {
     Foil,
     /// Etched foil.
     Etched,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
+    #[serde(untagged)]
     /// Unknown frame effect
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
+    #[serde(other)]
     /// Unknown frame effect
     Unknown,
 }

src/card/frame_effect.rs

@@ -84,10 +84,18 @@ pub enum FrameEffect {
     Vehicle,
     /// Spree
     Spree,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     /// Unknown frame effect
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     /// Unknown frame effect

src/card/layout.rs

@@ -71,10 +71,18 @@ pub enum Layout {
     Mutate,
     /// Case
     Case,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     /// Unknown layout
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     /// Unknown layout

src/card/promo_types.rs

@@ -92,10 +92,18 @@ pub enum PromoType {
     UpsideDownBack,
     Vault,
     Wizardsplaynetwork,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     /// Unknown variant
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     Unknown,

src/card/security_stamp.rs

@@ -20,10 +20,18 @@ pub enum SecurityStamp {
     Circle,
     Arena,
     Heart,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     /// Unknown frame effect
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     /// Unknown frame effect

src/format.rs

@@ -39,9 +39,17 @@ pub enum Format {
     Timeless,
     StandardBrawl,
     HistoricBrawl,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     Unknown,

src/lib.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![deny(missing_docs)]
 //! [Scryfall](https://scryfall.com) provides a REST-like API for ingesting our card data
 //! programatically. The API exposes information available on the regular site

src/search/param/compare.rs

@@ -1,8 +1,7 @@
 //! This module defines the [`Compare`] type, which represents a comparison
 //! operator and right-hand side of a comparison expression. Certain
-//! [`ParamValue`][crate::search::param::value::ParamValue] subtraits are
-//! implemented for `Compare<T>`, depending on whether Scryfall syntax supports
-//! comparing for that.
+//! [`ParamValue`] subtraits are implemented for `Compare<T>`, depending on
+//! whether Scryfall syntax supports comparing for that.
 //!
 //! To construct a `Compare` instance, use the helper functions defined in this
 //! module: [`lt`], [`lte`], [`gt`], [`gte`], [`eq`], and [`neq`].

src/set/set_type.rs

@@ -66,10 +66,18 @@ pub enum SetType {
     Arsenal,
     /// Mini game sets
     Minigame,
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(feature = "unknown_variants")]
     #[serde(untagged)]
     /// Unknown set type
     Unknown(Box<str>),
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(feature = "unknown_variants", feature = "unknown_variants_slim")))
+    )]
     #[cfg(all(not(feature = "unknown_variants"), feature = "unknown_variants_slim"))]
     #[serde(other)]
     /// Unknown set type

src/uri.rs

@@ -19,7 +19,7 @@ use crate::list::{List, ListIter};
 ///
 /// The `fetch` method handles requesting the resource from the API endpoint,
 /// and deserializing it into a `T` object. If the type parameter is
-/// [`List`][crate::list::List]`<_>`, then additional methods `fetch_iter`
+/// [`List`]`<_>`, then additional methods `fetch_iter`
 /// and `fetch_all` are available, giving access to objects from all pages
 /// of the collection.
 #[derive(Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]

tests/variants-feature/default_variants.rs

@@ -1,5 +1,5 @@
 use scryfall::{
-    card::{FrameEffect, Layout, PromoType, SecurityStamp},
+    card::{Finishes, FrameEffect, Layout, PromoType, SecurityStamp},
     format::Format,
     set::SetType,
 };
@@ -28,4 +28,5 @@ fn deserialize() {
     assert!(serde_json::from_str::<SetType>(r#""foo""#).is_err());
     assert!(serde_json::from_str::<PromoType>(r#""foo""#).is_err());
     assert!(serde_json::from_str::<SecurityStamp>(r#""foo""#).is_err());
+    assert!(serde_json::from_str::<Finishes>(r#""foo""#).is_err());
 }

tests/variants-feature/unknown_variants.rs

@@ -1,5 +1,5 @@
 use scryfall::{
-    card::{FrameEffect, Layout, PromoType, SecurityStamp},
+    card::{Finishes, FrameEffect, Layout, PromoType, SecurityStamp},
     format::Format,
     set::SetType,
 };
@@ -240,6 +240,16 @@ fn match_on_security_stamp(s: SecurityStamp) {
     }
 }
 
+#[allow(dead_code)]
+fn match_on_finishes(f: Finishes) {
+    match f {
+        Finishes::Nonfoil => todo!(),
+        Finishes::Foil => todo!(),
+        Finishes::Etched => todo!(),
+        Finishes::Unknown(_) => todo!(),
+    }
+}
+
 #[test]
 fn deserialize() {
     assert_eq!(
@@ -266,4 +276,8 @@ fn deserialize() {
         serde_json::from_str::<SecurityStamp>(r#""foo""#).unwrap(),
         SecurityStamp::Unknown("foo".into())
     );
+    assert_eq!(
+        serde_json::from_str::<Finishes>(r#""foo""#).unwrap(),
+        Finishes::Unknown("foo".into())
+    );
 }

tests/variants-feature/unknown_variants_slim.rs

@@ -1,5 +1,5 @@
 use scryfall::{
-    card::{FrameEffect, Layout, PromoType, SecurityStamp},
+    card::{Finishes, FrameEffect, Layout, PromoType, SecurityStamp},
     format::Format,
     set::SetType,
 };
@@ -247,6 +247,16 @@ fn match_on_security_stamp(s: SecurityStamp) {
     }
 }
 
+#[allow(dead_code)]
+fn match_on_finishes(f: Finishes) {
+    match f {
+        Finishes::Nonfoil => todo!(),
+        Finishes::Foil => todo!(),
+        Finishes::Etched => todo!(),
+        Finishes::Unknown(_) => todo!(),
+    }
+}
+
 #[test]
 fn deserialize() {
     assert_eq!(
@@ -273,4 +283,8 @@ fn deserialize() {
         serde_json::from_str::<SecurityStamp>(r#""frontier""#).unwrap(),
         SecurityStamp::Unknown,
     );
+    assert_eq!(
+        serde_json::from_str::<Finishes>(r#""foo""#).unwrap(),
+        Finishes::Unknown,
+    );
 }