docs: inline document-features usage, remove dep.

Re-implements https://github.com/gfx-rs/wgpu/pull/4886 (CC @Wumpf)
without the `document-features` crate, which has issues integrating into
Firefox builds after being `cargo vendor`ed into its repository. This
issue is being tracked against
https://github.com/slint-ui/document-features/issues/20. Once resolved,
I expect that we will want to revert this PR in its entirety, since
`document-features` is still a good addition to `wgpu`'s documentation
story.

Internally, consensus has already been achieved for this change.
Firefox's ability to build unfortunately take priority over this
particular convenience. Hopefully, we won't have to compromise shortly!

I tested this by ensuring that the HTML output of our existing
`document_features::document_features!(…)` usage was exactly the same.
There should be exactly zero regressions in the current state of
documentation for users. For maintainers, I have added a disclaimer that
one needs to keep changes in sync. with the relevant `Cargo.toml`
manifests.

Cargo.lock

@@ -1100,15 +1100,6 @@ dependencies = [
  "libloading 0.8.1",
 ]
 
-[[package]]
-name = "document-features"
-version = "0.2.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e493c573fce17f00dcab13b6ac057994f3ce17d1af4dc39bfd482b83c6eb6157"
-dependencies = [
- "litrs",
-]
-
 [[package]]
 name = "downcast-rs"
 version = "1.2.0"
@@ -1948,12 +1939,6 @@ version = "0.4.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "969488b55f8ac402214f3f5fd243ebb7206cf82de60d3172994707a4bcc2b829"
 
-[[package]]
-name = "litrs"
-version = "0.2.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f9275e0933cf8bb20f008924c0cb07a0692fe54d8064996520bf998de9eb79aa"
-
 [[package]]
 name = "lock_api"
 version = "0.4.11"
@@ -4009,7 +3994,6 @@ version = "0.18.0"
 dependencies = [
  "arrayvec 0.7.4",
  "cfg-if",
- "document-features",
  "js-sys",
  "log",
  "naga",
@@ -4035,7 +4019,6 @@ dependencies = [
  "bit-vec",
  "bitflags 2.4.1",
  "codespan-reporting",
- "document-features",
  "log",
  "naga",
  "parking_lot",

Cargo.toml

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

wgpu-core/Cargo.toml

@@ -94,7 +94,6 @@ arrayvec = "0.7"
 bit-vec = "0.6"
 bitflags = "2"
 codespan-reporting = "0.11"
-document-features.workspace = true
 log = "0.4"
 # parking_lot 0.12 switches from `winapi` to `windows`; permit either
 parking_lot = ">=0.11,<0.13"

wgpu-core/src/lib.rs

@@ -3,8 +3,36 @@
 //! into other language-specific user-friendly libraries.
 //!
 //! ## Feature flags
-#![doc = document_features::document_features!()]
+// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`!
 //!
+//! - **`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. Disale 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.
+//! - **`trace`** --- Enable API tracing.
+//! - **`replay`** --- Enable API replaying
+//! - **`serial-pass`** --- Enable serializable compute/render passes, and bundle encoders.
+//! - **`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

@@ -155,7 +155,6 @@ 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,7 +3,52 @@
 //! To start using the API, create an [`Instance`].
 //!
 //! ## Feature flags
-#![doc = document_features::document_features!()]
+// 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.
+//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS
+//!   using.
+//! - **`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.
+//!     - ⚠️ WIP: This automatically disables use of WebGPU. See
+//!       [#2804](https://github.com/gfx-rs/wgpu/issues/3514).
+//!
+//! ### Shading language support
+//!
+//! - **`spirv`** --- Enable accepting SPIR-V shaders as input.
+//! - **`glsl`** --- Enable accepting GLSL shaders as input.
+//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL 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.
+//! - **`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.
 //!
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]