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 3d5bec659b9cf19f1c64274de0d11808d771cc66, 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](https://github.com/slint-ui/document-features/issues/20).

Cargo.lock

@@ -1108,6 +1108,15 @@ dependencies = [
  "libloading 0.8.1",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef5282ad69563b5fc40319526ba27e0e7363d552a896f0297d54f767717f9b95"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "downcast-rs"
 version = "1.2.0"
@@ -1946,6 +1955,12 @@ version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "01cda141df6706de531b6c46c3a33ecca755538219bd484262fa09410c13539c"
 
+[[package]]
+name = "litrs"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ce301924b7887e9d637144fdade93f9dfff9b60981d4ac161db09720d39aa5"
+
 [[package]]
 name = "lock_api"
 version = "0.4.11"
@@ -3967,6 +3982,7 @@ dependencies = [
  "arrayvec 0.7.4",
  "cfg-if",
  "cfg_aliases",
+ "document-features",
  "js-sys",
  "log",
  "naga",
@@ -3994,6 +4010,7 @@ dependencies = [
  "bytemuck",
  "cfg_aliases",
  "codespan-reporting",
+ "document-features",
  "indexmap",
  "log",
  "naga",

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.
+## Allow writing of trace capture files. See [`Adapter::request_device`].
-## 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`!
+#![doc = document_features::document_features!()]
-//!
-//! ### 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.
 //!
 //! ### Feature Aliases
 //!