Fix documentation of re-exports

bevyengine · Aug 12, 2024 · 26a2eff · 26a2eff
1 parent d4df901
commit 26a2eff
Show file tree

Hide file tree

Showing 10 changed files with 19 additions and 18 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -49,6 +49,7 @@ ref_as_ptr = "warn"
 unsafe_op_in_unsafe_fn = "warn"
 missing_docs = "warn"
 unsafe_code = "deny"
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(docsrs_dep)'] }
 
 [lints]
 workspace = true
@@ -3363,6 +3364,11 @@ lto = "fat"
 panic = "abort"
 
 [package.metadata.docs.rs]
+# This cfg is needed so that #[doc(fake_variadic)] is correctly propagated for
+# impls for re-exported traits. See https://github.com/rust-lang/cargo/issues/8811
+# for details on why this is needed. Since dependencies don't expect to be built
+# with `--cfg docsrs` (and thus fail to compile) we use a different cfg.
+rustc-args = ["--cfg docsrs_dep"]
 rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

diff --git a/crates/bevy_app/src/lib.rs b/crates/bevy_app/src/lib.rs
@@ -1,6 +1,6 @@
 // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 #![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(any(docsrs, docsrs_dep), feature(doc_auto_cfg, rustdoc_internals))]
 #![forbid(unsafe_code)]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",

diff --git a/crates/bevy_dylib/src/lib.rs b/crates/bevy_dylib/src/lib.rs
@@ -1,6 +1,4 @@
-// `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
-#![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",
     html_favicon_url = "https://bevyengine.org/assets/icon.png"

diff --git a/crates/bevy_ecs/src/lib.rs b/crates/bevy_ecs/src/lib.rs
@@ -3,7 +3,7 @@
 #![doc = include_str!("../README.md")]
 // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 #![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(any(docsrs, docsrs_dep), feature(doc_auto_cfg, rustdoc_internals))]
 #![allow(unsafe_code)]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",

diff --git a/crates/bevy_internal/src/lib.rs b/crates/bevy_internal/src/lib.rs
@@ -1,6 +1,4 @@
-// `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
-#![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![forbid(unsafe_code)]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",

diff --git a/crates/bevy_reflect/src/lib.rs b/crates/bevy_reflect/src/lib.rs
@@ -2,7 +2,7 @@
 #![allow(missing_docs)]
 // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 #![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(any(docsrs, docsrs_dep), feature(doc_auto_cfg, rustdoc_internals))]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",
     html_favicon_url = "https://bevyengine.org/assets/icon.png"

diff --git a/crates/bevy_render/src/lib.rs b/crates/bevy_render/src/lib.rs
@@ -3,7 +3,7 @@
 #![allow(unsafe_code)]
 // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 #![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(any(docsrs, docsrs_dep), feature(doc_auto_cfg, rustdoc_internals))]
 #![doc(
     html_logo_url = "https://bevyengine.org/assets/icon.png",
     html_favicon_url = "https://bevyengine.org/assets/icon.png"

diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
@@ -29,7 +29,7 @@
 
 // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 #![allow(internal_features)]
-#![cfg_attr(docsrs, feature(rustdoc_internals))]
+#![cfg_attr(any(docsrs, docsrs_dep), feature(rustdoc_internals))]
 
 #[cfg(feature = "bevy_app")]
 /// Provides [`App`](bevy_app::App) and [`SubApp`](bevy_app::SubApp) with state installation methods

diff --git a/crates/bevy_utils/macros/src/lib.rs b/crates/bevy_utils/macros/src/lib.rs
@@ -134,7 +134,7 @@ impl Parse for AllTuples {
 /// ```
 /// // `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
 /// #![allow(internal_features)]
-/// #![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+/// #![cfg_attr(any(docsrs, docsrs_dep), feature(rustdoc_internals))]
 /// ```
 ///
 /// ```
@@ -280,6 +280,7 @@ fn choose_ident_tuples<'a>(
 }
 
 fn fake_variadic_attrs(len: usize, i: usize) -> TokenStream2 {
+    let cfg = quote! { any(docsrs, docsrs_dep) };
     match i {
         // An empty tuple (i.e. the unit type) is still documented separately,
         // so no `#[doc(hidden)]` here.
@@ -291,10 +292,10 @@ fn fake_variadic_attrs(len: usize, i: usize) -> TokenStream2 {
                 Span2::call_site(),
             );
             quote! {
-                #[cfg_attr(docsrs, doc(fake_variadic))]
-                #[cfg_attr(docsrs, doc = #doc)]
+                #[cfg_attr(#cfg, doc(fake_variadic))]
+                #[cfg_attr(#cfg, doc = #doc)]
             }
         }
-        _ => quote! { #[cfg_attr(docsrs, doc(hidden))] },
+        _ => quote! { #[cfg_attr(#cfg, doc(hidden))] },
     }
 }
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,7 +1,5 @@
 #![allow(clippy::single_component_path_imports)]
-// `rustdoc_internals` is needed for `#[doc(fake_variadics)]`
-#![allow(internal_features)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg, rustdoc_internals))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 //! [![Bevy Logo](https://bevyengine.org/assets/bevy_logo_docs.svg)](https://bevyengine.org)
 //!