Various documentation improvements. (#5017)

4 files changed, 107 insertions, 4 deletions

diff --git a/docs/user-guide/06-interfaces-generics.md b/docs/user-guide/06-interfaces-generics.md
index 61bc43f89..df51ac950 100644
--- a/docs/user-guide/06-interfaces-generics.md
+++ b/docs/user-guide/06-interfaces-generics.md
@@ -104,6 +104,22 @@ Generic value parameters can also be defined using the traditional C-style synta
 void g1<typename T, int n>() { ... }
 ```
 
+Slang allows multiple `where` clauses, and multiple interface types in a single `where` clause:
+```csharp
+struct MyType<T, U>
+    where T: IFoo, IBar
+    where U : IBaz<T>
+{
+}
+// equivalent to:
+struct MyType<T, U>
+    where T: IFoo
+    where T : IBar
+    where U : IBaz<T>
+{
+}
+```
+
 Supported Constructs in Interface Definitions
 -----------------------------------------------------
 
@@ -793,6 +809,61 @@ void main()
 See  [if-let syntax](convenience-features.html#if_let-syntax) for more details.
 
 
+Generic Interfaces
+------------------
+
+Slang allows interfaces themselves to be generic. A common use of generic interfaces is to define the `IEnumerable` type:
+```csharp
+interface IEnumerator<T>
+{
+    This moveNext();
+    bool isEnd();
+    T getValue();
+}
+
+interface IEnumerable<T>
+{
+    assoicatedtype Enumerator : IEnumerator<T>;
+    Enumerator getEnumerator();
+}
+```
+
+You can constrain a generic type parameter to conform to a generic interface:
+```csharp
+void traverse<TElement, TCollection>(TCollection c)
+    where TCollection : IEnumerable<TElement>
+{
+    ...
+}
+```
+
+
+Generic Extensions
+----------------------
+You can use generic extensions to extend a generic type. For example,
+```csharp
+interface IFoo { void foo(); }
+interface IBar { void bar(); }
+
+struct MyType<T : IFoo>
+{
+    void foo() { ... }
+}
+
+// Extend `MyType<T>` so it conforms to `IBar`.
+extension<T:IFoo> MyType<T> : IBar
+{
+    void bar() { ... }
+}
+// Equivalent to:
+__generic<T:IFoo>
+extension MyType<T> : IBar
+{
+    void bar() { ... }
+}
+```
+
+
 Extensions to Interfaces
 -----------------------------
 
diff --git a/docs/user-guide/09-targets.md b/docs/user-guide/09-targets.md
index e1219a39d..d6aebab0c 100644
--- a/docs/user-guide/09-targets.md
+++ b/docs/user-guide/09-targets.md
@@ -302,14 +302,14 @@ Metal
 > #### Note ####
 > Slang support for Metal is a work in progress.
 
-Metal is a shading language exclusive on Apple slicons. The functionality from Metal is similar to DX12 or Vulkan with more or less features.
+Metal is a shading language exclusive on Apple platforms. The functionality from Metal is similar to DX12 or Vulkan with more or less features.
 
 ### Pipelines
 
-Metal includes rasterization, compute, and ray tracing pipelines with the same set of stages as described for D3D12 above.
+Metal includes vertex, fragment, task, mesh and tessellation stages for rasterization, as well as compute, and ray tracing stages.
 
 > #### Note ####
-> Ray-tracing and Mesh support for Metal is a work in progress.
+> Ray-tracing support for Metal is a work in progress.
 
 ### Parameter Passing
 
diff --git a/docs/user-guide/a2-01-spirv-target-specific.md b/docs/user-guide/a2-01-spirv-target-specific.md
index a1ecbfefd..e0d6fd69b 100644
--- a/docs/user-guide/a2-01-spirv-target-specific.md
+++ b/docs/user-guide/a2-01-spirv-target-specific.md
@@ -134,7 +134,7 @@ SPIR-V 1.5 with [SPV_EXT_shader_atomic_float16_add](https://github.com/KhronosGr
 ConstantBuffer, (RW/RasterizerOrdered)StructuredBuffer, (RW/RasterizerOrdered)ByteAddressBuffer
 -----------------------------------------------------------------------------------------------
 
-Each member in a `ConstantBuffer` will be emitted as `uniform` parameter.
+Each member in a `ConstantBuffer` will be emitted as `uniform` parameter in a uniform block.
 StructuredBuffer and ByteAddressBuffer are translated to a shader storage buffer with `readonly` layout.
 RWStructuredBuffer and RWByteAddressBuffer are translated to a shader storage buffer with `read-write` layout.
 RasterizerOrderedStructuredBuffer and RasterizerOrderedByteAddressBuffer will use an extension, `SPV_EXT_fragment_shader_interlock`.
@@ -156,6 +156,34 @@ It is similar to `ConstantBuffer` in HLSL, and `ParameterBlock` can include not
 When both ordinary data fields and resource typed fields exist in a parameter block, all ordinary data fields will be grouped together into a uniform buffer and appear as a binding 0 of the resulting descriptor set.
 
 
+Push Constants
+---------------------
+
+By default, a `uniform` parameter defined in the parameter list of an entrypoint function is translated to a push constant in SPIRV, if the type of the parameter is ordinary data type (no resources/textures).
+All `uniform` parameter defined in global scope are grouped together and placed in a default constant bbuffer. You can make a global uniform parameter laid out as a push constant by using the `[vk::push_constant]` attribute
+on the uniform parameter.
+
+Specialization Constants
+------------------------
+
+You can specify a global constant to translate into a SPIRV specialization constant with the `[SpecializationConstant]` attribute.
+For example:
+```csharp
+[SpecializationConstant]
+const int myConst = 1; // Maps to a SPIRV specialization constant
+```
+
+By default, Slang will automatically assign `constant_id` number for specialization constants. If you wish to explicitly specify them, use `[vk::constant_id]` attribute:
+```csharp
+[vk::constant_id(1)]
+const int myConst = 1;
+```
+
+Alternatively, the GLSL `layout` syntax is also supported by Slang:
+```glsl
+layout(constant_id = 1) const int MyConst = 1;
+```
+
 SPIR-V specific Compiler options
 --------------------------------
 
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index df1b4ba9d..77c4f16d8 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -83,6 +83,8 @@
 <li data-link="interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
 <li data-link="interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
 <li data-link="interfaces-generics#is-and-as-operator"><span>`is` and `as` Operator</span></li>
+<li data-link="interfaces-generics#generic-interfaces"><span>Generic Interfaces</span></li>
+<li data-link="interfaces-generics#generic-extensions"><span>Generic Extensions</span></li>
 <li data-link="interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
 <li data-link="interfaces-generics#variadic-generics"><span>Variadic Generics</span></li>
 <li data-link="interfaces-generics#builtin-interfaces"><span>Builtin Interfaces</span></li>
@@ -207,6 +209,8 @@
 <li data-link="spirv-target-specific#supported-atomic-types-for-each-target"><span>Supported atomic types for each target</span></li>
 <li data-link="spirv-target-specific#constantbuffer-rwrasterizerorderedstructuredbuffer-rwrasterizerorderedbyteaddressbuffer"><span>ConstantBuffer, (RW/RasterizerOrdered)StructuredBuffer, (RW/RasterizerOrdered)ByteAddressBuffer</span></li>
 <li data-link="spirv-target-specific#parameterblock-for-spir-v-target"><span>ParameterBlock for SPIR-V target</span></li>
+<li data-link="spirv-target-specific#push-constants"><span>Push Constants</span></li>
+<li data-link="spirv-target-specific#specialization-constants"><span>Specialization Constants</span></li>
 <li data-link="spirv-target-specific#spir-v-specific-compiler-options"><span>SPIR-V specific Compiler options</span></li>
 <li data-link="spirv-target-specific#spir-v-specific-attributes"><span>SPIR-V specific Attributes </span></li>
 <li data-link="spirv-target-specific#multiple-entry-points-support"><span>Multiple entry points support</span></li>