Revert "docs: inline document-features usage, remove dep." (#5169)

* docs: sync. `wgpu/Cargo.toml` feature comments with `lib.rs`

* Revert "docs: inline `document-features` usage, remove dep."

This reverts commit 3d5bec6, with an
update to `document-features`, and preferring to keep new `feature`
content. To be clear, the only difference I have observed is the
addition of the `serde` feature.

In case it shortens anyone's search, the specific issue resolved is
[`slint-ui/document-features`#20](slint-ui/document-features#20).

Cargo.toml

@@ -77,6 +77,7 @@ cfg_aliases = "0.1"
 cfg-if = "1"
 codespan-reporting = "0.11"
 ctor = "0.2"
+document-features = "0.2.8"
 encase = "0.7"
 env_logger = "0.10"
 fern = "0.6"

wgpu-core/Cargo.toml

@@ -101,6 +101,7 @@ bit-vec = "0.6"
 bitflags = "2"
 bytemuck = { version = "1.14", optional = true }
 codespan-reporting = "0.11"
+document-features.workspace = true
 indexmap = "2"
 log = "0.4"
 once_cell = "1"

wgpu-core/src/lib.rs

@@ -3,36 +3,8 @@
 //! into other language-specific user-friendly libraries.
 //!
 //! ## Feature flags
-// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`!
+#![doc = document_features::document_features!()]
 //!
-//! - **`api_log_info`** --- Log all API entry points at info instead of trace level.
-//! - **`resource_log_info`** --- Log resource lifecycle management at info instead of trace level.
-//! - **`link`** _(enabled by default)_ --- Use static linking for libraries. Disable to manually
-//!   link. Enabled by default.
-//! - **`renderdoc`** --- Support the Renderdoc graphics debugger:
-//!   [https://renderdoc.org/](https://renderdoc.org/)
-//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition
-//!   to the validation carried out at public APIs in all builds.
-//! - **`serde`** --- Enables serialization via `serde` on common wgpu types.
-//! - **`trace`** --- Enable API tracing.
-//! - **`replay`** --- Enable API replaying
-//! - **`wgsl`** --- Enable `ShaderModuleSource::Wgsl`
-//! - **`fragile-send-sync-non-atomic-wasm`** --- Implement `Send` and `Sync` on Wasm, but only if
-//!   atomics are not enabled.
-//!
-//!   WebGL/WebGPU objects can not be shared between threads. However, it can be useful to
-//!   artificially mark them as `Send` and `Sync` anyways to make it easier to write cross-platform
-//!   code. This is technically _very_ unsafe in a multithreaded environment, but on a wasm binary
-//!   compiled without atomics we know we are definitely not in a multithreaded environment.
-//!
-//!  ### Backends, passed through to wgpu-hal
-//!
-//!  - **`metal`** --- Enable the `metal` backend.
-//!  - **`vulkan`** --- Enable the `vulkan` backend.
-//!  - **`gles`** --- Enable the `GLES` backend.
-//!
-//!    This is used for all of GLES, OpenGL, and WebGL.
-//!  - **`dx12`** --- Enable the `dx12` backend.
 
 // When we have no backends, we end up with a lot of dead or otherwise unreachable code.
 #![cfg_attr(

wgpu/Cargo.toml

@@ -38,20 +38,24 @@ dx12 = ["wgc?/dx12"]
 ## Enables the Metal backend on macOS & iOS.
 metal = ["wgc?/metal"]
 
+## Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
+webgpu = ["naga?/wgsl-out"]
+
 ## Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS using.
 angle = ["wgc?/gles"]
 
 ## Enables the Vulkan backend on macOS & iOS.
 vulkan-portability = ["wgc?/vulkan"]
 
-## Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
-webgpu = ["naga?/wgsl-out"]
-
 ## Enables the GLES backend on Wasm
 ##
 ## * ⚠️ WIP: Currently will also enable GLES dependencies on any other targets.
 webgl = ["hal", "wgc/gles"]
 
+#! **Note:** In the documentation, if you see that an item depends on a backend,
+#! it means that the item is only available when that backend is enabled _and_ the backend
+#! is supported on the current platform.
+
 #! ### Shading language support
 # --------------------------------------------------------------------
 
@@ -81,8 +85,7 @@ api_log_info = ["wgc/api_log_info"]
 ## Enables serialization via `serde` on common wgpu types.
 serde = ["dep:serde", "wgc/serde"]
 
-## Allow writing of trace capture files.
-## See [`Adapter::request_device`].
+## Allow writing of trace capture files. See [`Adapter::request_device`].
 trace = ["serde", "wgc/trace"]
 
 ## Allow deserializing of trace capture files that were written with the `trace` feature.
@@ -163,6 +166,7 @@ optional = true
 [dependencies]
 arrayvec.workspace = true
 cfg-if.workspace = true
+document-features.workspace = true
 log.workspace = true
 parking_lot.workspace = true
 profiling.workspace = true

wgpu/src/lib.rs

@@ -3,55 +3,7 @@
 //! To start using the API, create an [`Instance`].
 //!
 //! ## Feature flags
-// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`!
-//!
-//! ### Backends
-//!
-//! ⚠️ WIP: Not all backends can be manually configured today. On Windows & Linux the **Vulkan & GLES
-//! backends are always enabled**. See [#3514](https://github.com/gfx-rs/wgpu/issues/3514) for more
-//! details.
-//!
-//! - **`dx12`** _(enabled by default)_ ---   Enables the DX12 backend on Windows.
-//! - **`metal`** _(enabled by default)_ --- Enables the Metal backend on macOS & iOS.
-//! - **`webgpu`** _(enabled by default)_ --- Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
-//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS.
-//! - **`vulkan-portability`** --- Enables the Vulkan backend on macOS & iOS.
-//! - **`webgl`** --- Enables the GLES backend on Wasm.
-//!     - ⚠️ WIP: Currently will also enable GLES dependencies on any other targets.
-//!
-//! **Note:** In the documentation, if you see that an item depends on a backend,
-//! it means that the item is only available when that backend is enabled _and_ the backend
-//! is supported on the current platform.
-//!
-//! ### Shading language support
-//!
-//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input.
-//! - **`spirv`** --- Enable accepting SPIR-V shaders as input.
-//! - **`glsl`** --- Enable accepting GLSL shaders as input.
-//! - **`naga-ir`** --- Enable accepting Naga IR shaders as input.
-//!
-//! ### Logging & Tracing
-//!
-//! The following features do not have any effect on the WebGPU backend.
-//!
-//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition
-//!   to the validation carried out at public APIs in all builds.
-//! - **`api_log_info`** --- Log all API entry points at info instead of trace level.
-//! - **`serde`** --- Enables serialization via `serde` on common wgpu types.
-//! - **`trace`** --- Allow writing of trace capture files. See [`Adapter::request_device`].
-//! - **`replay`** --- Allow deserializing of trace capture files that were written with the `trace`
-//!   feature. To replay a trace file use the [wgpu
-//!   player](https://github.com/gfx-rs/wgpu/tree/trunk/player).
-//!
-//! ### Other
-//!
-//! - **`fragile-send-sync-non-atomic-wasm`** --- Implement `Send` and `Sync` on Wasm, but only if
-//!   atomics are not enabled.
-//!
-//!   WebGL/WebGPU objects can not be shared between threads. However, it can be useful to
-//!   artificially mark them as `Send` and `Sync` anyways to make it easier to write cross-platform
-//!   code. This is technically _very_ unsafe in a multithreaded environment, but on a wasm binary
-//!   compiled without atomics we know we are definitely not in a multithreaded environment.
+#![doc = document_features::document_features!()]
 //!
 //! ### Feature Aliases
 //!