From c5e649dbd9c995278f1a702587091999f66be62d Mon Sep 17 00:00:00 2001
From: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
Date: Tue, 22 Feb 2022 22:17:15 -0500
Subject: [PATCH] Improve shader support documentation

---
 README.md       | 15 +++++++++++++++
 wgpu/Cargo.toml |  1 +
 wgpu/src/lib.rs |  3 +++
 3 files changed, 19 insertions(+)

diff --git a/README.md b/README.md
index a6e894c45c..11c526e9e9 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,21 @@ We have a [wiki](https://github.com/gfx-rs/wgpu/wiki) that serves as a knowledge
 
 :white_check_mark: = First Class Support — :ok: = Best Effort Support — :hammer_and_wrench: = Unsupported, but support in progress
 
+### Shader Support
+
+wgpu supports shaders in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/), SPIR-V, and GLSL. 
+Both [HLSL](https://github.com/Microsoft/DirectXShaderCompiler) and [GLSL](https://github.com/KhronosGroup/glslang) 
+have compilers to target SPIR-V. All of these shader languages can be used with any backend, we
+will handle all of the conversion. Additionally, support for these shader inputs is not going away.
+
+While WebGPU does not support any shader language other than WGSL, we will automatically convert your
+non-WGSL shaders if you're running on WebGPU.
+
+WGSL is always supported by default, but GLSL and SPIR-V need features enabled to compile in support.
+
+To enable SPIR-V shaders, enable the `spirv` feature of wgpu.  
+To enable GLSL shaders, enable the `glsl` feature of wgpu.
+
 ### Angle
 
 [Angle](http://angleproject.org) is a translation layer from GLES to other backends, developed by Google.
diff --git a/wgpu/Cargo.toml b/wgpu/Cargo.toml
index 2c7ccf3fcd..ca03d016c6 100644
--- a/wgpu/Cargo.toml
+++ b/wgpu/Cargo.toml
@@ -23,6 +23,7 @@ autotests = false
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [lib]
 
diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs
index 3ea9c3271e..d940164619 100644
--- a/wgpu/src/lib.rs
+++ b/wgpu/src/lib.rs
@@ -2,6 +2,7 @@
 //!
 //! To start using the API, create an [`Instance`].
 
+#![cfg_attr(docsrs, feature(doc_cfg))] // Allow doc(cfg(feature = "")) for showing in docs that something is feature gated.
 #![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/master/logo.png")]
 #![warn(missing_docs)]
 
@@ -762,11 +763,13 @@ impl Drop for ShaderModule {
 pub enum ShaderSource<'a> {
     /// SPIR-V module represented as a slice of words.
     #[cfg(feature = "spirv")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "spirv")))]
     SpirV(Cow<'a, [u32]>),
     /// GLSL module as a string slice.
     ///
     /// Note: GLSL is not yet fully supported and must be a specific ShaderStage.
     #[cfg(feature = "glsl")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "glsl")))]
     Glsl {
         /// The source code of the shader.
         shader: Cow<'a, str>,