Repository: gfx-rs/wgpu (language: rust)

Issue:
`wgpu::PresentMode::AutoNoVsync`'s documentation is confusing
Hi there! I don't use `wgpu` directly, but I do use `bevy`, which copies `wgpu::PresentMode` and all its documentation.

The `AutoNoVsync` variant for `PresentMode` has some confusing documentation which I think should be updated. Specifically, after telling us the order in which it chooses presentation modes, it then confusingly has the text"(on web)". What does "on web" refer to here, and what does it mean? Does it mean that the Fifo mode is only considered when on web platforms, or does it mean something else?

Whatever it means, it's probably best to separate this "on web" clarification out into its own sentence. For example, "The Fifo mode is only considered on web platforms."

Thanks for your hard work, whoever responds to this.


Discussion / hints:
Looking over [the current documentation](https://docs.rs/wgpu/0.17.0/wgpu/enum.PresentMode.html) for which platforms support which modes, it seems like the correct clarified text would be that "The `Fifo` mode will only ever be chosen on web, as all other platforms support at least one of `Immediate` or `Mailbox`".

Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d04c43e689..b09aeb297b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -223,6 +223,7 @@ By @brodycj in [#6924](https://github.com/gfx-rs/wgpu/pull/6924).
 ### Documentation
 
 - Improved documentation around pipeline caches and `TextureBlitter`. By @DJMcNab in [#6978](https://github.com/gfx-rs/wgpu/pull/6978) and [#7003](https://github.com/gfx-rs/wgpu/pull/7003).
+- Improved documentation of `PresentMode`. By @kpreid in [#7211](https://github.com/gfx-rs/wgpu/pull/7211).
 
 - Added a hello window example. By @laycookie in [#6992](https://github.com/gfx-rs/wgpu/pull/6992).
 
diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index bea3f73d00..9587216dee 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -4900,74 +4900,96 @@ impl<T> Default for CommandEncoderDescriptor<Option<T>> {
     }
 }
 
-/// Behavior of the presentation engine based on frame rate.
+/// Timing and queueing with which frames are actually displayed to the user.
+///
+/// Use this as part of a [`SurfaceConfiguration`] to control the behavior of
+/// [`SurfaceTexture::present()`].
+///
+/// Some modes are only supported by some backends.
+/// You can use one of the `Auto*` modes, [`Fifo`](Self::Fifo),
+/// or choose one of the supported modes from [`SurfaceCapabilities::present_modes`].
+///
+/// [presented]: ../wgpu/struct.SurfaceTexture.html#method.present
+/// [`SurfaceTexture::present()`]: ../wgpu/struct.SurfaceTexture.html#method.present
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum PresentMode {
-    /// Chooses `FifoRelaxed` -> `Fifo` based on availability.
+    /// Chooses the first supported mode out of:
+    ///
+    /// 1. [`FifoRelaxed`](Self::FifoRelaxed)
+    /// 2. [`Fifo`](Self::Fifo)
     ///
-    /// Because of the fallback behavior, it is supported everywhere.
+    /// Because of the fallback behavior, this is supported everywhere.
     AutoVsync = 0,
-    /// Chooses `Immediate` -> `Mailbox` -> `Fifo` (on web) based on availability.
+
+    /// Chooses the first supported mode out of:
+    ///
+    /// 1. [`Immediate`](Self::Immediate)
+    /// 2. [`Mailbox`](Self::Mailbox)
+    /// 3. [`Fifo`](Self::Fifo)
     ///
-    /// Because of the fallback behavior, it is supported everywhere.
+    /// Because of the fallback behavior, this is supported everywhere.
     AutoNoVsync = 1,
+
     /// Presentation frames are kept in a First-In-First-Out queue approximately 3 frames
     /// long. Every vertical blanking period, the presentation engine will pop a frame
     /// off the queue to display. If there is no frame to display, it will present the same
     /// frame again until the next vblank.
     ///
-    /// When a present command is executed on the gpu, the presented image is added on the queue.
+    /// When a present command is executed on the GPU, the presented image is added on the queue.
     ///
-    /// No tearing will be observed.
+    /// Calls to [`Surface::get_current_texture()`] will block until there is a spot in the queue.
     ///
-    /// Calls to `Surface::get_current_texture` will block until there is a spot in the queue.
+    /// * **Tearing:** No tearing will be observed.
+    /// * **Supported on**: All platforms.
+    /// * **Also known as**: "Vsync On"
     ///
-    /// Supported on all platforms.
+    /// This is the [default](Self::default) value for `PresentMode`.
+    /// If you don't know what mode to choose, choose this mode.
     ///
-    /// If you don't know what mode to choose, choose this mode. This is traditionally called "Vsync On".
+    /// [`Surface::get_current_texture()`]: ../wgpu/struct.Surface.html#method.get_current_texture
     #[default]
     Fifo = 2,
+
     /// Presentation frames are kept in a First-In-First-Out queue approximately 3 frames
     /// long. Every vertical blanking period, the presentation engine will pop a frame
     /// off the queue to display. If there is no frame to display, it will present the
     /// same frame until there is a frame in the queue. The moment there is a frame in the
     /// queue, it will immediately pop the frame off the queue.
     ///
-    /// When a present command is executed on the gpu, the presented image is added on the queue.
+    /// When a present command is executed on the GPU, the presented image is added on the queue.
     ///
-    /// Tearing will be observed if frames last more than one vblank as the front buffer.
+    /// Calls to [`Surface::get_current_texture()`] will block until there is a spot in the queue.
     ///
-    /// Calls to `Surface::get_current_texture` will block until there is a spot in the queue.
+    /// * **Tearing**:
+    ///   Tearing will be observed if frames last more than one vblank as the front buffer.
+    /// * **Supported on**: AMD on Vulkan.
+    /// * **Also known as**: "Adaptive Vsync"
     ///
-    /// Supported on AMD on Vulkan.
-    ///
-    /// This is traditionally called "Adaptive Vsync"
+    /// [`Surface::get_current_texture()`]: ../wgpu/struct.Surface.html#method.get_current_texture
     FifoRelaxed = 3,
+
     /// Presentation frames are not queued at all. The moment a present command
     /// is executed on the GPU, the presented image is swapped onto the front buffer
     /// immediately.
     ///
-    /// Tearing can be observed.
-    ///
-    /// Supported on most platforms except older DX12 and Wayland.
-    ///
-    /// This is traditionally called "Vsync Off".
+    /// * **Tearing**: Tearing can be observed.
+    /// * **Supported on**: Most platforms except older DX12 and Wayland.
+    /// * **Also known as**: "Vsync Off"
     Immediate = 4,
+
     /// Presentation frames are kept in a single-frame queue. Every vertical blanking period,
     /// the presentation engine will pop a frame from the queue. If there is no frame to display,
     /// it will present the same frame again until the next vblank.
     ///
-    /// When a present command is executed on the gpu, the frame will be put into the queue.
+    /// When a present command is executed on the GPU, the frame will be put into the queue.
     /// If there was already a frame in the queue, the new frame will _replace_ the old frame
     /// on the queue.
     ///
-    /// No tearing will be observed.
-    ///
-    /// Supported on DX12 on Windows 10, NVidia on Vulkan and Wayland on Vulkan.
-    ///
-    /// This is traditionally called "Fast Vsync"
+    /// * **Tearing**: No tearing will be observed.
+    /// * **Supported on**: DX12 on Windows 10, NVidia on Vulkan and Wayland on Vulkan.
+    /// * **Also known as**: "Fast Vsync"
     Mailbox = 5,
 }
 


Test patch: