Adjust InstanceDescriptor docs

wgpu-types/src/instance.rs

@@ -8,15 +8,34 @@ use crate::Backends;
 use crate::{Backend, DownlevelFlags};
 
 /// Options for creating an instance.
+///
+/// If you want to allow control of instance settings via environment variables, call either
+/// [`InstanceDescriptor::from_env_or_default()`] or [`InstanceDescriptor::with_env()`]. Each type
+/// within this descriptor has its own equivalent methods, so you can select which options you want
+/// to expose to influence from the environment.
 #[derive(Clone, Debug)]
 pub struct InstanceDescriptor {
-    /// Which `Backends` to enable.
+    /// Which [`Backends`] to enable.
+    ///
+    /// [`Backends::BROWSER_WEBGPU`] has an additional effect:
+    /// If it is set and a [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu)
+    /// object is present, this instance will *only* be able to create WebGPU adapters.
+    ///
+    /// ⚠️ On some browsers this check is insufficient to determine whether WebGPU is supported,
+    /// as the browser may define the `navigator.gpu` object, but be unable to create any WebGPU adapters.
+    /// For targeting _both_ WebGPU & WebGL, it is recommended to use [`crate::util::new_instance_with_webgpu_detection`](../wgpu/util/fn.new_instance_with_webgpu_detection.html).
+    ///
+    /// If you instead want to force use of WebGL, either disable the `webgpu` compile-time feature
+    /// or don't include the [`Backends::BROWSER_WEBGPU`] flag in this field.
+    /// If it is set and WebGPU support is *not* detected, the instance will use `wgpu-core`
+    /// to create adapters, meaning that if the `webgl` feature is enabled, it is able to create
+    /// a WebGL adapter.
     pub backends: Backends,
     /// Flags to tune the behavior of the instance.
     pub flags: InstanceFlags,
     /// Memory budget thresholds used by some backends.
     pub memory_budget_thresholds: MemoryBudgetThresholds,
-    /// Options the control the behavior of various backends.
+    /// Options the control the behavior of specific backends.
     pub backend_options: BackendOptions,
 }
 

wgpu/src/api/instance.rs

@@ -21,7 +21,7 @@ bitflags::bitflags! {
     }
 }
 
-/// Context for all other wgpu objects. Instance of wgpu.
+/// Contains the various entry points to start interacting with the system's GPUs.
 ///
 /// This is the first thing you create when using wgpu.
 /// Its primary use is to create [`Adapter`]s and [`Surface`]s.
@@ -84,33 +84,14 @@ impl Instance {
         backends
     }
 
-    /// Create an new instance of wgpu.
-    ///
-    /// # Arguments
-    ///
-    /// - `instance_desc` - Has fields for which [backends][Backends] wgpu will choose
-    ///   during instantiation, and which [DX12 shader compiler][Dx12Compiler] wgpu will use.
-    ///
-    ///   [`Backends::BROWSER_WEBGPU`] takes a special role:
-    ///   If it is set and a [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu)
-    ///   object is present, this instance will *only* be able to create WebGPU adapters.
-    ///
-    ///   ⚠️ On some browsers this check is insufficient to determine whether WebGPU is supported,
-    ///   as the browser may define the `navigator.gpu` object, but be unable to create any WebGPU adapters.
-    ///   For targeting _both_ WebGPU & WebGL is recommended to use [`crate::util::new_instance_with_webgpu_detection`].
-    ///
-    ///   If you instead want to force use of WebGL, either disable the `webgpu` compile-time feature
-    ///   or don't add the [`Backends::BROWSER_WEBGPU`] flag to the the `instance_desc`'s `backends` field.
-    ///   If it is set and WebGPU support is *not* detected, the instance will use wgpu-core
-    ///   to create adapters. Meaning that if the `webgl` feature is enabled, it is able to create
-    ///   a WebGL adapter.
+    /// Create an new instance of wgpu using the given options and enabled backends.
     ///
     /// # Panics
     ///
-    /// If no backend feature for the active target platform is enabled,
-    /// this method will panic, see [`Instance::enabled_backend_features()`].
+    /// - If no backend feature for the active target platform is enabled,
+    ///   this method will panic; see [`Instance::enabled_backend_features()`].
     #[allow(clippy::allow_attributes, unreachable_code)]
-    pub fn new(_instance_desc: &InstanceDescriptor) -> Self {
+    pub fn new(desc: &InstanceDescriptor) -> Self {
         if Self::enabled_backend_features().is_empty() {
             panic!(
                 "No wgpu backend feature that is implemented for the target platform was enabled. \
@@ -121,14 +102,14 @@ impl Instance {
         #[cfg(webgpu)]
         {
             let is_only_available_backend = !cfg!(wgpu_core);
-            let requested_webgpu = _instance_desc.backends.contains(Backends::BROWSER_WEBGPU);
+            let requested_webgpu = desc.backends.contains(Backends::BROWSER_WEBGPU);
             let support_webgpu = crate::backend::get_browser_gpu_property()
                 .map(|maybe_gpu| maybe_gpu.is_some())
                 .unwrap_or(false);
 
             if is_only_available_backend || (requested_webgpu && support_webgpu) {
                 return Self {
-                    inner: crate::backend::ContextWebGpu::new(_instance_desc).into(),
+                    inner: crate::backend::ContextWebGpu::new(desc).into(),
                 };
             }
         }
@@ -136,10 +117,13 @@ impl Instance {
         #[cfg(wgpu_core)]
         {
             return Self {
-                inner: crate::backend::ContextWgpuCore::new(_instance_desc).into(),
+                inner: crate::backend::ContextWgpuCore::new(desc).into(),
             };
         }
 
+        // Silence unused variable warnings without adding _ to the parameter name (which shows up in docs).
+        let _ = desc;
+
         unreachable!(
             "Earlier check of `enabled_backend_features` should have prevented getting here!"
         );

wgpu/src/lib.rs

@@ -1,6 +1,23 @@
-//! A cross-platform graphics and compute library based on [WebGPU](https://gpuweb.github.io/gpuweb/).
+//! `wgpu` is a cross-platform, safe, pure-Rust graphics API. It runs natively on
+//! Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.
 //!
-//! To start using the API, create an [`Instance`].
+//! The API is based on the [WebGPU standard][webgpu]. It serves as the core of the
+//! WebGPU integration in Firefox, Servo, and Deno.
+//!
+//! [webgpu]: https://gpuweb.github.io/gpuweb/
+//!
+//! ## Getting Started
+//!
+//! The main entry point to the API is the [`Instance`] type, from which you can create [`Adapter`], [`Device`], and [`Surface`].
+//!
+//! If you are new to `wgpu` and graphics programming, we recommend reading
+//! <https://sotrh.github.io/learn-wgpu/> and <https://webgpufundamentals.org/>. The latter is a WebGPU
+//! tutorial, but the concepts are nearly identical to `wgpu`.
+//!
+//! There are examples for this version [available on GitHub](https://github.com/gfx-rs/wgpu/tree/v26/examples#readme)..
+//!
+//! The API is refcounted, so all handles are cloneable, and if you create a resource which references another,
+//! it will automatically keep dependent resources alive.
 //!
 //! ## Feature flags
 #![doc = document_features::document_features!()]