Change crates document to use feature-conditional code instead of fea…

…ture-conditional documentation to work around crates.io rendering bug.

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 2.0.1 - 2025-01-06
+
+### Change
+- Updated how code conditioned on the `sync` flag is written in the crate
+  documentation to work around a [crates.io doc rendering
+  bug](https://github.com/rust-lang/crates.io/issues/10331).
+
 ## 2.0.0 - 2025-01-06
 ### Added
 - Gated the sync/`Arc` downcasting functionality behind a new `sync` feature

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "downcast-rs"
 edition = "2021"
-version = "2.0.0"
+version = "2.0.1"
 rust-version = "1.56"
 repository = "https://github.com/marcianx/downcast-rs"
 description = """

README.md

@@ -19,14 +19,14 @@ Add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-downcast-rs = "2.0.0"
+downcast-rs = "2.0.1"
 ```
 
 This crate is `no_std` compatible. To use it without `std`:
 
 ```toml
 [dependencies]
-downcast-rs = { version = "2.0.0", default-features = false }
+downcast-rs = { version = "2.0.1", default-features = false }
 ```
 
 To make a trait downcastable, make it extend either `downcast::Downcast` or
@@ -35,15 +35,18 @@ below.
 
 Since 2.0.0, the minimum supported Rust version is 1.56.
 
-## #[macro_use]
-## extern crate downcast_rs;
-## use downcast_rs::{Downcast, DowncastSync};
+```rust
+# use downcast_rs::{Downcast, impl_downcast};
+# #[cfg(feature = "sync")]
+# use downcast_rs::DowncastSync;
 trait Trait: Downcast {}
 impl_downcast!(Trait);
 
 // Also supports downcasting `Arc`-ed trait objects by extending `DowncastSync`
 // and starting `impl_downcast!` with `sync`.
+# #[cfg(feature = "sync")]
 trait TraitSync: DowncastSync {}
+# #[cfg(feature = "sync")]
 impl_downcast!(sync TraitSync);
 
 // With type parameters.
@@ -66,18 +69,30 @@ impl_downcast!(concrete TraitConcrete1<u32>);
 
 trait TraitConcrete2<T: Copy>: Downcast { type H; }
 impl_downcast!(concrete TraitConcrete2<u32> assoc H=f64);
-## fn main() {}
-```rust
+# fn main() {}
+```
 
+## Example without generics
 
-// Import macro via `macro_use` pre-1.30.
-#[macro_use]
-extern crate downcast_rs;
+```rust
+# use std::rc::Rc;
+# #[cfg(feature = "sync")]
+# use std::sync::Arc;
+# use downcast_rs::impl_downcast;
+# #[cfg(not(feature = "sync"))]
+# use downcast_rs::Downcast;
+# #[cfg(feature = "sync")]
 use downcast_rs::DowncastSync;
 
 // To create a trait with downcasting methods, extend `Downcast` or `DowncastSync`
 // and run `impl_downcast!()` on the trait.
+# #[cfg(not(feature = "sync"))]
+# trait Base: Downcast {}
+# #[cfg(not(feature = "sync"))]
+# impl_downcast!(Base);
+# #[cfg(feature = "sync")]
 trait Base: DowncastSync {}
+# #[cfg(feature = "sync")]
 impl_downcast!(sync Base);  // `sync` => also produce `Arc` downcasts.
 
 // Concrete types implementing Base.
@@ -90,7 +105,7 @@ impl Base for Bar {}
 
 fn main() {
     // Create a trait object.
-    let mut base: Box<Base> = Box::new(Foo(42));
+    let mut base: Box<dyn Base> = Box::new(Foo(42));
 
     // Try sequential downcasts.
     if let Some(foo) = base.downcast_ref::<Foo>() {
@@ -101,29 +116,29 @@ fn main() {
 
     assert!(base.is::<Foo>());
 
-    // Fail to convert `Box<Base>` into `Box<Bar>`.
+    // Fail to convert `Box<dyn Base>` into `Box<Bar>`.
     let res = base.downcast::<Bar>();
     assert!(res.is_err());
     let base = res.unwrap_err();
-    // Convert `Box<Base>` into `Box<Foo>`.
+    // Convert `Box<dyn Base>` into `Box<Foo>`.
     assert_eq!(42, base.downcast::<Foo>().map_err(|_| "Shouldn't happen.").unwrap().0);
 
     // Also works with `Rc`.
-    let mut rc: Rc<Base> = Rc::new(Foo(42));
+    let mut rc: Rc<dyn Base> = Rc::new(Foo(42));
     assert_eq!(42, rc.downcast_rc::<Foo>().map_err(|_| "Shouldn't happen.").unwrap().0);
 
     // Since this trait is `Sync`, it also supports `Arc` downcasts.
-    let mut arc: Arc<Base> = Arc::new(Foo(42));
+    # #[cfg(feature = "sync")]
+    let mut arc: Arc<dyn Base> = Arc::new(Foo(42));
+    # #[cfg(feature = "sync")]
     assert_eq!(42, arc.downcast_arc::<Foo>().map_err(|_| "Shouldn't happen.").unwrap().0);
 }
 ```
 
 ## Example with a generic trait with associated types and constraints
 
 ```rust
-// Can call macro via namespace since rust 1.30.
-extern crate downcast_rs;
-use downcast_rs::Downcast;
+use downcast_rs::{Downcast, impl_downcast};
 
 // To create a trait with downcasting methods, extend `Downcast` or `DowncastSync`
 // and run `impl_downcast!()` on the trait.
@@ -139,7 +154,7 @@ impl Base<u32> for Bar { type H = f32; }
 
 fn main() {
     // Create a trait object.
-    let mut base: Box<Base<u32, H=f32>> = Box::new(Bar(42.0));
+    let mut base: Box<dyn Base<u32, H=f32>> = Box::new(Bar(42.0));
 
     // Try sequential downcasts.
     if let Some(foo) = base.downcast_ref::<Foo>() {

src/lib.rs

@@ -19,14 +19,14 @@
 //!
 //! ```toml
 //! [dependencies]
-//! downcast-rs = "2.0.0"
+//! downcast-rs = "2.0.1"
 //! ```
 //!
 //! This crate is `no_std` compatible. To use it without `std`:
 //!
 //! ```toml
 //! [dependencies]
-//! downcast-rs = { version = "2.0.0", default-features = false }
+//! downcast-rs = { version = "2.0.1", default-features = false }
 //! ```
 //!
 //! To make a trait downcastable, make it extend either `downcast::Downcast` or
@@ -35,17 +35,18 @@
 //!
 //! Since 2.0.0, the minimum supported Rust version is 1.56.
 //!
-#![cfg_attr(feature = "sync", doc = "```")]
-#![cfg_attr(not(feature = "sync"), doc = "```ignore")]
-//! # #[macro_use]
-//! # extern crate downcast_rs;
-//! # use downcast_rs::{Downcast, DowncastSync};
+//! ```rust
+//! # use downcast_rs::{Downcast, impl_downcast};
+//! # #[cfg(feature = "sync")]
+//! # use downcast_rs::DowncastSync;
 //! trait Trait: Downcast {}
 //! impl_downcast!(Trait);
 //!
 //! // Also supports downcasting `Arc`-ed trait objects by extending `DowncastSync`
 //! // and starting `impl_downcast!` with `sync`.
+//! # #[cfg(feature = "sync")]
 //! trait TraitSync: DowncastSync {}
+//! # #[cfg(feature = "sync")]
 //! impl_downcast!(sync TraitSync);
 //!
 //! // With type parameters.
@@ -73,18 +74,25 @@
 //!
 //! # Example without generics
 //!
-#![cfg_attr(feature = "sync", doc = "```")]
-#![cfg_attr(not(feature = "sync"), doc = "```ignore")]
+//! ```rust
 //! # use std::rc::Rc;
+//! # #[cfg(feature = "sync")]
 //! # use std::sync::Arc;
-//! // Import macro via `macro_use` pre-1.30.
-//! #[macro_use]
-//! extern crate downcast_rs;
+//! # use downcast_rs::impl_downcast;
+//! # #[cfg(not(feature = "sync"))]
+//! # use downcast_rs::Downcast;
+//! # #[cfg(feature = "sync")]
 //! use downcast_rs::DowncastSync;
 //!
 //! // To create a trait with downcasting methods, extend `Downcast` or `DowncastSync`
 //! // and run `impl_downcast!()` on the trait.
+//! # #[cfg(not(feature = "sync"))]
+//! # trait Base: Downcast {}
+//! # #[cfg(not(feature = "sync"))]
+//! # impl_downcast!(Base);
+//! # #[cfg(feature = "sync")]
 //! trait Base: DowncastSync {}
+//! # #[cfg(feature = "sync")]
 //! impl_downcast!(sync Base);  // `sync` => also produce `Arc` downcasts.
 //!
 //! // Concrete types implementing Base.
@@ -120,17 +128,17 @@
 //!     assert_eq!(42, rc.downcast_rc::<Foo>().map_err(|_| "Shouldn't happen.").unwrap().0);
 //!
 //!     // Since this trait is `Sync`, it also supports `Arc` downcasts.
+//!     # #[cfg(feature = "sync")]
 //!     let mut arc: Arc<dyn Base> = Arc::new(Foo(42));
+//!     # #[cfg(feature = "sync")]
 //!     assert_eq!(42, arc.downcast_arc::<Foo>().map_err(|_| "Shouldn't happen.").unwrap().0);
 //! }
 //! ```
 //!
 //! # Example with a generic trait with associated types and constraints
 //!
-//! ```
-//! // Can call macro via namespace since rust 1.30.
-//! extern crate downcast_rs;
-//! use downcast_rs::Downcast;
+//! ```rust
+//! use downcast_rs::{Downcast, impl_downcast};
 //!
 //! // To create a trait with downcasting methods, extend `Downcast` or `DowncastSync`
 //! // and run `impl_downcast!()` on the trait.