From bd2d8cd4ca5e826a9f428ae5d5808acf113590d7 Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@switchb.org>
Date: Thu, 18 Jul 2024 15:46:04 -0700
Subject: [PATCH] Disable wgpu-core documentation as a workaround for #4905.

This enables `cargo doc` to succeed in a reasonable amount of time,
as long as the reader isn't looking for documentation for `wgpu-core`
itself.
---
 CHANGELOG.md         |  1 +
 wgpu-core/Cargo.toml |  8 ++++++++
 wgpu-core/src/lib.rs | 14 ++++++++++++++
 3 files changed, 23 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 149c58cde91..b51b7f3ad9e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,7 @@ Bottom level categories:
 #### General
 
 - Fix profiling with `tracy`. By @waywardmonkeys in [#5988](https://github.com/gfx-rs/wgpu/pull/5988)
+- As a workaround for [issue #4905](https://github.com/gfx-rs/wgpu/issues/4905), `wgpu-core` is undocumented unless the `wgpu-core-doc` feature is enabled. By @kpreid in [#5987](https://github.com/gfx-rs/wgpu/pull/5987)
 
 ## 22.0.0 (2024-07-17)
 
diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml
index 2e645a54067..8c68a9b3932 100644
--- a/wgpu-core/Cargo.toml
+++ b/wgpu-core/Cargo.toml
@@ -85,6 +85,14 @@ fragile-send-sync-non-atomic-wasm = [
     "wgt/fragile-send-sync-non-atomic-wasm",
 ]
 
+## Enable full documentation.
+## If this feature is not enabled, `wgpu-core`'s documentation will be empty.
+## This feature is a workaround for <https://github.com/rust-lang/rust/issues/114891>
+## tracked in wgpu as <https://github.com/gfx-rs/wgpu/issues/4905>,
+## to enable projects which do not need `wgpu-core` documentation to still use `cargo doc`
+## practically. When that bug is fixed, this feature should be removed.
+wgpu-core-doc = []
+
 #! ### Backends, passed through to wgpu-hal
 # --------------------------------------------------------------------
 
diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs
index 36105c90e6e..0cf195687a4 100644
--- a/wgpu-core/src/lib.rs
+++ b/wgpu-core/src/lib.rs
@@ -2,6 +2,20 @@
 //! It is designed for integration into browsers, as well as wrapping
 //! into other language-specific user-friendly libraries.
 //!
+#![cfg_attr(
+    not(any(not(doc), feature = "wgpu-core-doc")),
+    doc = "\
+## Documentation hidden
+
+As a workaround for [an issue in rustdoc](https://github.com/rust-lang/rust/issues/114891)
+that [affects `wgpu-core` documentation builds \
+severely](https://github.com/gfx-rs/wgpu/issues/4905),
+the documentation for `wgpu-core` is empty unless built with
+`cargo doc --features wgpu-core-doc`, which may take a very long time.
+"
+)]
+#![cfg(any(not(doc), feature = "wgpu-core-doc"))]
+//!
 //! ## Feature flags
 #![doc = document_features::document_features!()]
 //!