From 8219a64ecb2a0cc52d179e548b0415e0778da27f Mon Sep 17 00:00:00 2001
From: Aron Granberg <aron.granberg@gmail.com>
Date: Wed, 22 Apr 2020 12:50:06 +0200
Subject: [PATCH] [rs] Improve docs for BindingType

---
 wgpu/src/lib.rs | 70 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs
index af805e22cd..6a2f09d327 100644
--- a/wgpu/src/lib.rs
+++ b/wgpu/src/lib.rs
@@ -242,28 +242,96 @@ pub struct Binding<'a> {
     pub resource: BindingResource<'a>,
 }
 
-/// Specific type of a binding..
+/// Specific type of a binding.
+/// WebGPU spec: https://gpuweb.github.io/gpuweb/#dictdef-gpubindgrouplayoutentry
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 pub enum BindingType {
+    /// A buffer for uniform values.
+    ///
+    /// Example GLSL syntax:
+    /// ```
+    /// layout(std140, binding = 0)
+    /// uniform Globals {
+    ///     vec2 aUniform;
+    ///     vec2 anotherUniform;
+    /// };
+    /// ```
     UniformBuffer {
+        /// Indicates that the binding has a dynamic offset.
+        /// One offset must be passed to [RenderPass::set_bind_group] for each dynamic binding in increasing order of binding number.
         dynamic: bool,
     },
+    /// A storage buffer.
+    ///
+    /// Example GLSL syntax:
+    /// ```
+    /// layout (set=0, binding=0) buffer myStorageBuffer {
+    ///     vec4 myElement[];
+    /// };
+    /// ```
     StorageBuffer {
+        /// Indicates that the binding has a dynamic offset.
+        /// One offset must be passed to [RenderPass::set_bind_group] for each dynamic binding in increasing order of binding number.
         dynamic: bool,
+        /// The buffer can only be read in the shader and it must be annotated with `readonly`.
+        ///
+        /// Example GLSL syntax:
+        /// ```
+        /// layout (set=0, binding=0) readonly buffer myStorageBuffer {
+        ///     vec4 myElement[];
+        /// };
+        /// ```
         readonly: bool,
     },
+    /// A sampler that can be used to sample a texture.
+    ///
+    /// Example GLSL syntax:
+    /// ```
+    /// layout(binding = 0)
+    /// uniform sampler s;
+    /// ```
     Sampler {
+        /// Use as a comparison sampler instead of a normal sampler.
+        /// For more info take a look at the analogous functionality in OpenGL: https://www.khronos.org/opengl/wiki/Sampler_Object#Comparison_mode.
         comparison: bool,
     },
+    /// A texture.
+    ///
+    /// Example GLSL syntax:
+    /// ```
+    /// layout(binding = 0)
+    /// uniform texture2D t;
+    /// ```
     SampledTexture {
+        /// Dimension of the texture view that is going to be sampled.
         dimension: TextureViewDimension,
+        /// Component type of the texture.
+        /// This must be compatible with the format of the texture.
         component_type: TextureComponentType,
+        /// True if the texture has a sample count greater than 1.
         multisampled: bool,
     },
+    /// A storage texture.
+    /// Example GLSL syntax:
+    /// ```
+    /// layout(set=0, binding=0, r32f) uniform image2D myStorageImage;
+    /// ```
+    /// Note that the texture format must be specified in the shader as well.
+    /// A list of valid formats can be found in the specification here: https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.html#layout-qualifiers
     StorageTexture {
+        /// Dimension of the texture view that is going to be sampled.
         dimension: TextureViewDimension,
+        /// Component type of the texture.
+        /// This must be compatible with the format of the texture.
         component_type: TextureComponentType,
+        /// Format of the texture.
         format: TextureFormat,
+        /// The texture can only be read in the shader and it must be annotated with `readonly`.
+        ///
+        /// Example GLSL syntax:
+        /// ```
+        /// layout(set=0, binding=0, r32f) readonly uniform image2D myStorageImage;
+        /// ```
         readonly: bool,
     },
 }