Improve Capability System (#3555)

* Improve capability system.

* Update documentation.

* Tuning semantics.

* LSP: hierarchical diagnostics.

* Fix test.

* Fix test.

1 files changed, 23 insertions, 6 deletions

diff --git a/docs/user-guide/05-capabilities.md b/docs/user-guide/05-capabilities.md
index c20a43c75..5f69a3026 100644
--- a/docs/user-guide/05-capabilities.md
+++ b/docs/user-guide/05-capabilities.md
@@ -63,17 +63,34 @@ For example, requirement `spvShaderClockKHR + fragment` and requirement `spvShad
 
 ## Requirements in Parent Scope
 
-The capability requirement of a decl is always joined with the requirements declared in its parents.
-For example:
+The capability requirement of a decl is always merged with the requirements declared in its parents. If the decl declares requirements for additional compilation targets, they are added
+to the requirement set as a separate disjunction.
+For example, given:
 ```csharp
-[require(spvShaderClockKHR)]
+[require(glsl)]
+[require(hlsl)]
 struct MyType
 {
-    [require(spvShaderClockKHR)]
-    void method() { ... }
+    [require(hlsl, hlsl_nvapi)]
+    [require(spirv)]
+    static void method() { ... }
+}
+```
+`MyType.method` will have requirement `glsl | hlsl + hlsl_nvapi | spirv`.
+
+The `[require]` attribute can also be used on module declarations, so that the requirement will
+apply to all decls within the module. For example:
+```csharp
+[require(glsl)]
+[require(hlsl)]
+[require(spirv)]
+module myModule;
+
+// myFunc has requirement glsl|hlsl|spirv
+public void myFunc()
+{
 }
 ```
-`MyType.method` has requirement `spvShaderClockKHR + spvShaderClockKHR`.
 
 ## Inferrence of Capability Requirements