doc: mark api elements gated behind a feature flag in rust doc

Cargo.toml

@@ -16,6 +16,7 @@ categories = ["development-tools::testing", "no-std"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 default = ["std", "colored", "float_cmp", "panic"]

justfile

@@ -76,5 +76,5 @@ clean:
     cargo clean
 
 # generate and open docs locally
-doc:
+doc $RUSTDOCFLAGS="--cfg docsrs":
     cargo +nightly doc --all-features --no-deps --open

src/assertions.rs

@@ -42,6 +42,8 @@ pub trait AssertEquality<E> {
 }
 
 /// Assert approximate equality for floating point numbers.
+#[cfg(feature = "float_cmp")]
+#[cfg_attr(docsrs, doc(cfg(feature = "float_cmp")))]
 pub trait AssertIsCloseToWithinMargin<E, M> {
     /// Verifies that the actual value is approximately equal to the expected
     /// value.
@@ -73,6 +75,8 @@ pub trait AssertIsCloseToWithinMargin<E, M> {
 }
 
 /// Assert approximate equality for floating point numbers.
+#[cfg(feature = "float_cmp")]
+#[cfg_attr(docsrs, doc(cfg(feature = "float_cmp")))]
 pub trait AssertIsCloseToWithDefaultMargin<E> {
     /// Verifies that the actual value is approximately equal to the expected
     /// value.
@@ -1007,6 +1011,8 @@ pub trait AssertIsSorted {
 
 /// Assert that the code under test panics, panics with a certain message or
 /// does not panic.
+#[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub trait AssertCodePanics {
     /// Verifies that the actual code under test does not panic.
     #[track_caller]

src/colored/mod.rs

@@ -38,6 +38,7 @@
 //! The functions provided by this module help with highlighting missing and
 //! unexpected parts when composing the failure message for an assertion.
 #[cfg(feature = "colored")]
+#[cfg_attr(docsrs, doc(cfg(feature = "colored")))]
 pub use with_colored_feature::{
     diff_format_for_mode, DIFF_FORMAT_BOLD, DIFF_FORMAT_RED_BLUE, DIFF_FORMAT_RED_GREEN,
     DIFF_FORMAT_RED_YELLOW,

src/colored/tests.rs

@@ -174,7 +174,7 @@ mod with_colored_and_std_features {
 
             let assertion = assert_that(42);
 
-            assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_BOLD);
+            prop_assert_eq!(assertion.diff_format(), &DIFF_FORMAT_BOLD);
         }
 
         #[test]
@@ -186,7 +186,7 @@ mod with_colored_and_std_features {
 
             let assertion = assert_that(42);
 
-            assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_RED_BLUE);
+            prop_assert_eq!(assertion.diff_format(), &DIFF_FORMAT_RED_BLUE);
         }
 
         #[test]
@@ -198,7 +198,7 @@ mod with_colored_and_std_features {
 
             let assertion = assert_that(42);
 
-            assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_RED_YELLOW);
+            prop_assert_eq!(assertion.diff_format(), &DIFF_FORMAT_RED_YELLOW);
         }
 
         #[test]
@@ -210,7 +210,7 @@ mod with_colored_and_std_features {
 
             let assertion = assert_that(42);
 
-            assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_NO_HIGHLIGHT);
+            prop_assert_eq!(assertion.diff_format(), &DIFF_FORMAT_NO_HIGHLIGHT);
         }
     }
 

src/expectations.rs

@@ -463,6 +463,7 @@ pub struct Predicate<F> {
 }
 
 #[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub use panic::{DoesNotPanic, DoesPanic};
 
 #[cfg(feature = "panic")]

src/lib.rs

@@ -18,7 +18,7 @@
 //!
 //! # Usage
 //!
-//! To write fluent assertions in tests import this crate's `prelude`
+//! To write fluent assertions in tests, import this crate's `prelude`
 //! module in your test module, like so:
 //!
 //! ```
@@ -140,7 +140,7 @@
 //! ```
 //!
 //! Or we can map a custom type that does not implement a required trait to some
-//! supported type, e.g. a tuple in this example:
+//! supported type, e.g., a tuple in this example:
 //!
 //! ```
 //! # use asserting::prelude::*;
@@ -169,10 +169,12 @@
 //!
 //! ## Assert that some code panics or does not panic
 //!
+//! Requires crate feature `panic`.
+//!
 //! ```
-//! # #[cfg(not(feature = "std"))]
+//! # #[cfg(not(feature = "panic"))]
 //! # fn main() {}
-//! # #[cfg(feature = "std")]
+//! # #[cfg(feature = "panic")]
 //! # fn main() {
 //! use asserting::prelude::*;
 //!
@@ -214,7 +216,7 @@
 //! an optional description of what we are going to assert. These attributes are
 //! all optional and must be set explicitly by the user.
 //!
-//! For convenience a set of macros with the same names as the functions above
+//! For convenience, a set of macros with the same names as the functions above
 //! is provided which set the expression and the code location for the user.
 //!
 //! * [`assert_that!`] - calls the [`assert_that`] function and sets the
@@ -565,6 +567,8 @@
 
 #![doc(html_root_url = "https://docs.rs/asserting/0.4.0")]
 #![cfg_attr(not(feature = "std"), no_std)]
+// Render feature requirements in docs.rs
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 #[cfg(not(feature = "std"))]
 #[allow(unused_imports)]

src/prelude.rs

@@ -24,11 +24,13 @@ pub use super::{
 };
 
 #[cfg(feature = "colored")]
+#[cfg_attr(docsrs, doc(cfg(feature = "colored")))]
 pub use super::colored::{
     DIFF_FORMAT_BOLD, DIFF_FORMAT_RED_BLUE, DIFF_FORMAT_RED_GREEN, DIFF_FORMAT_RED_YELLOW,
 };
 
 #[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub use super::{
     assert_that_code,
     spec::{assert_that_code, verify_that_code},

src/spec/mod.rs

@@ -130,6 +130,7 @@ macro_rules! verify_that {
 /// ```
 #[cfg(feature = "panic")]
 #[cfg_attr(feature = "panic", macro_export)]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 macro_rules! assert_that_code {
     ($subject:expr) => {
         $crate::prelude::assert_that_code($subject)
@@ -190,6 +191,7 @@ macro_rules! assert_that_code {
 /// ```
 #[cfg(feature = "panic")]
 #[cfg_attr(feature = "panic", macro_export)]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 macro_rules! verify_that_code {
     ($subject:expr) => {
         $crate::prelude::verify_that_code($subject)
@@ -339,6 +341,7 @@ pub fn verify_that<'a, S>(subject: S) -> Spec<'a, S, CollectFailures> {
 /// assert_that_code(|| { divide(7, 3); }).does_not_panic();
 /// ```
 #[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub fn assert_that_code<'a, S>(code: S) -> Spec<'a, Code<S>, PanicOnFail>
 where
     S: FnOnce(),
@@ -399,6 +402,7 @@ where
 /// ]);
 /// ```
 #[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub fn verify_that_code<'a, S>(code: S) -> Spec<'a, Code<S>, CollectFailures>
 where
     S: FnOnce(),
@@ -1086,6 +1090,7 @@ impl Display for Unknown {
 
 /// Wrapper type that holds a closure as code snippet.
 #[cfg(feature = "panic")]
+#[cfg_attr(docsrs, doc(cfg(feature = "panic")))]
 pub struct Code<F>(Rc<RefCell<Option<F>>>);
 
 #[cfg(feature = "panic")]