Document All Capability Atoms and Profiles (#5008)

* Document All Capability Atoms and Profiles

Fixes: #4125

Unimplemented Considerations:
1. This PR does not add support to query all capability-atom's from a command-line option. It is understood that this might be desired, due to this, the logic to generate `docs\user-guide\a3-02-reference-capability-atoms.md` was made to be "command-line friendly" so minimal changes are needed to pipe our documentation into a command-line option if this change is to be added.

Changes:
1. Added a way to document atoms inside `.capdef`. Method to document is described under `source\slang\slang-capabilities.capdef`. The goal is to error if a public atom does not have any form of documentation to ensure we always have up-to-date documentation to guide user on what an atom is/does.
    * The following `.capdef` file syntax was added
        * /// [HEADER_GROUP]
        * /// regular comment
2. When capability generator runs it auto-generates `docs\user-guide\a3-02-reference-capability-atoms.md`
3. Added to the user-guide 3 sections: `Reference`, `Reference -> Capability Profiles`, `Reference -> Capability atoms` section

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/user-guide/a3-01-reference-capability-profiles.md b/docs/user-guide/a3-01-reference-capability-profiles.md
new file mode 100644
index 000000000..175a76496
--- /dev/null
+++ b/docs/user-guide/a3-01-reference-capability-profiles.md
@@ -0,0 +1,49 @@
+---
+layout: user-guide
+---
+
+Capability Profiles
+============================
+
+### Accepted values of `-profile`:
+
+> Note: To 'make' your own 'profile's, try mixing capabilities with `-capability`.
+
+sm_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model
+
+vs_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + vertex shader
+
+ps_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + pixel shader
+
+hs_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + hull shader
+
+gs_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + geometry shader
+
+ds_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + domain shader
+
+cs_{4_0,4_1,5_0,5_1,6_0,6_1,6_2,6_3,6_4,6_5,6_6,6_7}
+* HLSL shader model + compute shader
+
+ms_6_{5,6,7}
+* HLSL shader model + mesh shader
+
+as_6_{5,6,7}
+* HLSL shader model + amplification shader
+
+lib_6_{1,2,3,4,5,6,7}
+* HLSL shader model for libraries
+
+glsl_{110,120,130,140,150,330,400,410,420,430,440,450,460}
+* GLSL versions
+
+spirv_1_{1,2,3,4,5,6}
+* SPIRV versions
+
+metallib_2_{3,4}
+* Metal versions
\ No newline at end of file