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

8 files changed, 2657 insertions, 61 deletions

diff --git a/docs/user-guide/a2-target-specific-features.md b/docs/user-guide/a2-target-specific-features.md
index e0d4ed9ba..2761d84e5 100644
--- a/docs/user-guide/a2-target-specific-features.md
+++ b/docs/user-guide/a2-target-specific-features.md
@@ -1,4 +1,3 @@
-
 ---
 layout: user-guide
 ---
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
diff --git a/docs/user-guide/a3-02-reference-capability-atoms.md b/docs/user-guide/a3-02-reference-capability-atoms.md
new file mode 100644
index 000000000..993c581b6
--- /dev/null
+++ b/docs/user-guide/a3-02-reference-capability-atoms.md
@@ -0,0 +1,1188 @@
+---
+layout: user-guide
+---
+
+Capability Atoms
+============================
+
+### Sections:
+
+1. [Targets](#Targets)
+2. [Stages](#Stages)
+3. [Versions](#Versions)
+4. [Extensions](#Extensions)
+5. [Compound Capabilities](#Compound-Capabilities)
+6. [Other](#Other)
+
+Targets
+----------------------
+*Capabilities to specify code generation targets (`glsl`, `spirv`...)*
+
+`textualTarget`
+> Represents a non-assembly code generation target.
+
+`hlsl`
+> Represents the HLSL code generation target.
+
+`glsl`
+> Represents the GLSL code generation target.
+
+`c`
+> Represents the C programming language code generation target.
+
+`cpp`
+> Represents the C++ programming language code generation target.
+
+`cuda`
+> Represents the CUDA code generation target.
+
+`metal`
+> Represents the Metal programming language code generation target.
+
+`spirv`
+> Represents the SPIR-V code generation target.
+
+Stages
+----------------------
+*Capabilities to specify code generation stages (`vertex`, `fragment`...)*
+
+`vertex`
+> Vertex shader stage
+
+`fragment`
+> Fragment shader stage
+
+`compute`
+> Compute shader stage
+
+`hull`
+> Hull shader stage
+
+`domain`
+> Domain shader stage
+
+`geometry`
+> Geometry shader stage
+
+`pixel`
+> Pixel shader stage
+
+`tesscontrol`
+> Tessellation Control shader stage
+
+`tesseval`
+> Tessellation Evaluation shader stage
+
+`raygen`
+> Ray-Generation shader stage & ray-tracing capabilities
+
+`raygeneration`
+> Ray-Generation shader stage & ray-tracing capabilities
+
+`intersection`
+> Intersection shader stage & ray-tracing capabilities
+
+`anyhit`
+> Any-Hit shader stage & ray-tracing capabilities
+
+`closesthit`
+> Closest-Hit shader stage & ray-tracing capabilities
+
+`callable`
+> Callable shader stage & ray-tracing capabilities
+
+`miss`
+> Ray-Miss shader stage & ray-tracing capabilities
+
+`mesh`
+> Mesh shader stage & mesh shader capabilities
+
+`amplification`
+> Amplification shader stage & mesh shader capabilities
+
+Versions
+----------------------
+*Capabilities to specify versions of a code generation target (`sm_5_0`, `GLSL_400`...)*
+
+`glsl_spirv_1_0`
+> Represents SPIR-V 1.0 through glslang.
+
+`glsl_spirv_1_1`
+> Represents SPIR-V 1.1 through glslang.
+
+`glsl_spirv_1_2`
+> Represents SPIR-V 1.2 through glslang.
+
+`glsl_spirv_1_3`
+> Represents SPIR-V 1.3 through glslang.
+
+`glsl_spirv_1_4`
+> Represents SPIR-V 1.4 through glslang.
+
+`glsl_spirv_1_5`
+> Represents SPIR-V 1.5 through glslang.
+
+`glsl_spirv_1_6`
+> Represents SPIR-V 1.6 through glslang.
+
+`metallib_2_3`
+> Represents MetalLib 2.3.
+
+`metallib_2_4`
+> Represents MetalLib 2.4.
+
+`metallib_3_0`
+> Represents MetalLib 3.0.
+
+`metallib_3_1`
+> Represents MetalLib 3.1.
+
+`metallib_latest`
+> Represents the latest MetalLib version.
+
+`hlsl_nvapi`
+> Represents HLSL NVAPI support.
+
+`dxil_lib`
+> Represents capabilities required for DXIL Library compilation.
+
+`spirv_1_0`
+> Represents SPIR-V 1.0 version.
+
+`spirv_1_1`
+> Represents SPIR-V 1.1 version, which includes SPIR-V 1.0.
+
+`spirv_1_2`
+> Represents SPIR-V 1.2 version, which includes SPIR-V 1.1.
+
+`spirv_1_3`
+> Represents SPIR-V 1.3 version, which includes SPIR-V 1.2.
+
+`spirv_1_4`
+> Represents SPIR-V 1.4 version, which includes SPIR-V 1.3.
+
+`spirv_1_5`
+> Represents SPIR-V 1.5 version, which includes SPIR-V 1.4 and additional extensions.
+
+`spirv_1_6`
+> Represents SPIR-V 1.6 version, which includes SPIR-V 1.5 and additional extensions.
+
+`spirv_latest`
+> Represents the latest SPIR-V version.
+
+`sm_4_0_version`
+> HLSL shader model 4.0 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_4_0`
+> HLSL shader model 4.0 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_4_1_version`
+> HLSL shader model 4.1 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_4_1`
+> HLSL shader model 4.1 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_5_0_version`
+> HLSL shader model 5.0 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_5_0`
+> HLSL shader model 5.0 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_5_1_version`
+> HLSL shader model 5.1 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_5_1`
+> HLSL shader model 5.1 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_0_version`
+> HLSL shader model 6.0 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_0`
+> HLSL shader model 6.0 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_1_version`
+> HLSL shader model 6.1 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_1`
+> HLSL shader model 6.1 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_2_version`
+> HLSL shader model 6.2 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_2`
+> HLSL shader model 6.2 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_3_version`
+> HLSL shader model 6.3 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_3`
+> HLSL shader model 6.3 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_4_version`
+> HLSL shader model 6.4 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_4`
+> HLSL shader model 6.4 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_5_version`
+> HLSL shader model 6.5 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_5`
+> HLSL shader model 6.5 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_6_version`
+> HLSL shader model 6.6 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_6`
+> HLSL shader model 6.6 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`sm_6_7_version`
+> HLSL shader model 6.7 and related capabilities of other targets.
+> Does not include related GLSL/SPIRV extensions.
+
+`sm_6_7`
+> HLSL shader model 6.7 and related capabilities of other targets.
+> Includes related GLSL/SPIRV extensions.
+
+`GLSL_130`
+> GLSL 130 and related capabilities of other targets.
+
+`GLSL_140`
+> GLSL 140 and related capabilities of other targets.
+
+`GLSL_150`
+> GLSL 150 and related capabilities of other targets.
+
+`GLSL_330`
+> GLSL 330 and related capabilities of other targets.
+
+`GLSL_400`
+> GLSL 400 and related capabilities of other targets.
+
+`GLSL_410`
+> GLSL 410 and related capabilities of other targets.
+
+`GLSL_420`
+> GLSL 420 and related capabilities of other targets.
+
+`GLSL_430`
+> GLSL 430 and related capabilities of other targets.
+
+`GLSL_440`
+> GLSL 440 and related capabilities of other targets.
+
+`GLSL_450`
+> GLSL 450 and related capabilities of other targets.
+
+`GLSL_460`
+> GLSL 460 and related capabilities of other targets.
+
+`cuda_sm_1_0`
+> cuda 1.0 and related capabilities of other targets.
+
+`cuda_sm_2_0`
+> cuda 2.0 and related capabilities of other targets.
+
+`cuda_sm_3_0`
+> cuda 3.0 and related capabilities of other targets.
+
+`cuda_sm_3_5`
+> cuda 3.5 and related capabilities of other targets.
+
+`cuda_sm_4_0`
+> cuda 4.0 and related capabilities of other targets.
+
+`cuda_sm_5_0`
+> cuda 5.0 and related capabilities of other targets.
+
+`cuda_sm_6_0`
+> cuda 6.0 and related capabilities of other targets.
+
+`cuda_sm_7_0`
+> cuda 7.0 and related capabilities of other targets.
+
+`cuda_sm_8_0`
+> cuda 8.0 and related capabilities of other targets.
+
+`cuda_sm_9_0`
+> cuda 9.0 and related capabilities of other targets.
+
+Extensions
+----------------------
+*Capabilities to specify extensions (`GL_EXT`, `SPV_EXT`...)*
+
+`SPV_EXT_fragment_shader_interlock`
+> Represents the SPIR-V extension for fragment shader interlock operations.
+
+`SPV_EXT_physical_storage_buffer`
+> Represents the SPIR-V extension for physical storage buffer.
+
+`SPV_EXT_fragment_fully_covered`
+> Represents the SPIR-V extension for SPV_EXT_fragment_fully_covered.
+
+`SPV_EXT_descriptor_indexing`
+> Represents the SPIR-V extension for descriptor indexing.
+
+`SPV_EXT_shader_atomic_float_add`
+> Represents the SPIR-V extension for atomic float add operations.
+
+`SPV_EXT_shader_atomic_float16_add`
+> Represents the SPIR-V extension for atomic float16 add operations.
+
+`SPV_EXT_shader_atomic_float_min_max`
+> Represents the SPIR-V extension for atomic float min/max operations.
+
+`SPV_EXT_mesh_shader`
+> Represents the SPIR-V extension for mesh shaders.
+
+`SPV_EXT_demote_to_helper_invocation`
+> Represents the SPIR-V extension for demoting to helper invocation.
+
+`SPV_KHR_fragment_shader_barycentric`
+> Represents the SPIR-V extension for fragment shader barycentric.
+
+`SPV_KHR_non_semantic_info`
+> Represents the SPIR-V extension for non-semantic information.
+
+`SPV_KHR_ray_tracing`
+> Represents the SPIR-V extension for ray tracing.
+
+`SPV_KHR_ray_query`
+> Represents the SPIR-V extension for ray queries.
+
+`SPV_KHR_ray_tracing_position_fetch`
+> Represents the SPIR-V extension for ray tracing position fetch.
+> Should be used with either SPV_KHR_ray_query or SPV_KHR_ray_tracing.
+
+`SPV_KHR_shader_clock`
+> Represents the SPIR-V extension for shader clock.
+
+`SPV_NV_shader_subgroup_partitioned`
+> Represents the SPIR-V extension for shader subgroup partitioned.
+
+`SPV_NV_ray_tracing_motion_blur`
+> Represents the SPIR-V extension for ray tracing motion blur.
+
+`SPV_NV_shader_invocation_reorder`
+> Represents the SPIR-V extension for shader invocation reorder.
+> Requires SPV_KHR_ray_tracing.
+
+`SPV_NV_shader_image_footprint`
+> Represents the SPIR-V extension for shader image footprint.
+
+`SPV_NV_compute_shader_derivatives`
+> Represents the SPIR-V extension for compute shader derivatives.
+
+`SPV_GOOGLE_user_type`
+> Represents the SPIR-V extension for SPV_GOOGLE_user_type.
+
+`spvAtomicFloat32AddEXT`
+> Represents the SPIR-V capability for atomic float 32 add operations.
+
+`spvAtomicFloat16AddEXT`
+> Represents the SPIR-V capability for atomic float 16 add operations.
+
+`spvInt64Atomics`
+> Represents the SPIR-V capability for 64-bit integer atomics.
+
+`spvAtomicFloat32MinMaxEXT`
+> Represents the SPIR-V capability for atomic float 32 min/max operations.
+
+`spvAtomicFloat16MinMaxEXT`
+> Represents the SPIR-V capability for atomic float 16 min/max operations.
+
+`spvDerivativeControl`
+> Represents the SPIR-V capability for 'derivative control' operations.
+
+`spvImageQuery`
+> Represents the SPIR-V capability for image query operations.
+
+`spvImageGatherExtended`
+> Represents the SPIR-V capability for extended image gather operations.
+
+`spvSparseResidency`
+> Represents the SPIR-V capability for sparse residency.
+
+`spvImageFootprintNV`
+> Represents the SPIR-V capability for image footprint.
+
+`spvMinLod`
+> Represents the SPIR-V capability for using minimum LOD operations.
+
+`spvFragmentShaderPixelInterlockEXT`
+> Represents the SPIR-V capability for using SPV_EXT_fragment_shader_interlock.
+
+`spvFragmentBarycentricKHR`
+> Represents the SPIR-V capability for using SPV_KHR_fragment_shader_barycentric.
+
+`spvFragmentFullyCoveredEXT`
+> Represents the SPIR-V capability for using SPV_EXT_fragment_fully_covered functionality.
+
+`spvGroupNonUniformBallot`
+> Represents the SPIR-V capability for group non-uniform ballot operations.
+
+`spvGroupNonUniformShuffle`
+> Represents the SPIR-V capability for group non-uniform shuffle operations.
+
+`spvGroupNonUniformArithmetic`
+> Represents the SPIR-V capability for group non-uniform arithmetic operations.
+
+`spvGroupNonUniformQuad`
+> Represents the SPIR-V capability for group non-uniform quad operations.
+
+`spvGroupNonUniformVote`
+> Represents the SPIR-V capability for group non-uniform vote operations.
+
+`spvGroupNonUniformPartitionedNV`
+> Represents the SPIR-V capability for group non-uniform partitioned operations.
+
+`spvRayTracingMotionBlurNV`
+> Represents the SPIR-V capability for ray tracing motion blur.
+
+`spvMeshShadingEXT`
+> Represents the SPIR-V capability for mesh shading.
+
+`spvRayTracingKHR`
+> Represents the SPIR-V capability for ray tracing.
+
+`spvRayTracingPositionFetchKHR`
+> Represents the SPIR-V capability for ray tracing position fetch.
+
+`spvRayQueryKHR`
+> Represents the SPIR-V capability for ray query.
+
+`spvRayQueryPositionFetchKHR`
+> Represents the SPIR-V capability for ray query position fetch.
+
+`spvShaderInvocationReorderNV`
+> Represents the SPIR-V capability for shader invocation reorder.
+
+`spvShaderClockKHR`
+> Represents the SPIR-V capability for shader clock.
+
+`spvShaderNonUniformEXT`
+> Represents the SPIR-V capability for non-uniform resource indexing.
+
+`spvShaderNonUniform`
+> Represents the SPIR-V capability for non-uniform resource indexing.
+
+`spvDemoteToHelperInvocationEXT`
+> Represents the SPIR-V capability for demoting to helper invocation.
+
+`spvDemoteToHelperInvocation`
+> Represents the SPIR-V capability for demoting to helper invocation.
+
+`GL_EXT_buffer_reference`
+> Represents the GL_EXT_buffer_reference extension.
+
+`GL_EXT_buffer_reference_uvec2`
+> Represents the GL_EXT_buffer_reference_uvec2 extension.
+
+`GL_EXT_debug_printf`
+> Represents the GL_EXT_debug_printf extension.
+
+`GL_EXT_demote_to_helper_invocation`
+> Represents the GL_EXT_demote_to_helper_invocation extension.
+
+`GL_EXT_fragment_shader_barycentric`
+> Represents the GL_EXT_fragment_shader_barycentric extension.
+
+`GL_EXT_mesh_shader`
+> Represents the GL_EXT_mesh_shader extension.
+
+`GL_EXT_nonuniform_qualifier`
+> Represents the GL_EXT_nonuniform_qualifier extension.
+
+`GL_EXT_ray_query`
+> Represents the GL_EXT_ray_query extension.
+
+`GL_EXT_ray_tracing`
+> Represents the GL_EXT_ray_tracing extension.
+
+`GL_EXT_ray_tracing_position_fetch_ray_tracing`
+> Represents the GL_EXT_ray_tracing_position_fetch_ray_tracing extension.
+
+`GL_EXT_ray_tracing_position_fetch_ray_query`
+> Represents the GL_EXT_ray_tracing_position_fetch_ray_query extension.
+
+`GL_EXT_ray_tracing_position_fetch`
+> Represents the GL_EXT_ray_tracing_position_fetch extension.
+
+`GL_EXT_samplerless_texture_functions`
+> Represents the GL_EXT_samplerless_texture_functions extension.
+
+`GL_EXT_shader_atomic_float`
+> Represents the GL_EXT_shader_atomic_float extension.
+
+`GL_EXT_shader_atomic_float_min_max`
+> Represents the GL_EXT_shader_atomic_float_min_max extension.
+
+`GL_EXT_shader_atomic_float2`
+> Represents the GL_EXT_shader_atomic_float2 extension.
+
+`GL_EXT_shader_atomic_int64`
+> Represents the GL_EXT_shader_atomic_int64 extension.
+
+`GL_EXT_shader_explicit_arithmetic_types_int64`
+> Represents the GL_EXT_shader_explicit_arithmetic_types_int64 extension.
+
+`GL_EXT_shader_image_load_store`
+> Represents the GL_EXT_shader_image_load_store extension.
+
+`GL_EXT_shader_realtime_clock`
+> Represents the GL_EXT_shader_realtime_clock extension.
+
+`GL_EXT_texture_query_lod`
+> Represents the GL_EXT_texture_query_lod extension.
+
+`GL_EXT_texture_shadow_lod`
+> Represents the GL_EXT_texture_shadow_lod extension.
+
+`GL_ARB_derivative_control`
+> Represents the GL_ARB_derivative_control extension.
+
+`GL_ARB_fragment_shader_interlock`
+> Represents the GL_ARB_fragment_shader_interlock extension.
+
+`GL_ARB_gpu_shader5`
+> Represents the GL_ARB_gpu_shader5 extension.
+
+`GL_ARB_shader_image_load_store`
+> Represents the GL_ARB_shader_image_load_store extension.
+
+`GL_ARB_shader_image_size`
+> Represents the GL_ARB_shader_image_size extension.
+
+`GL_ARB_texture_multisample`
+> Represents the GL_ARB_texture_multisample extension.
+
+`GL_ARB_shader_texture_image_samples`
+> Represents the GL_ARB_shader_texture_image_samples extension.
+
+`GL_ARB_sparse_texture`
+> Represents the GL_ARB_sparse_texture extension.
+
+`GL_ARB_sparse_texture2`
+> Represents the GL_ARB_sparse_texture2 extension.
+
+`GL_ARB_sparse_texture_clamp`
+> Represents the GL_ARB_sparse_texture_clamp extension.
+
+`GL_ARB_texture_gather`
+> Represents the GL_ARB_texture_gather extension.
+
+`GL_ARB_texture_query_levels`
+> Represents the GL_ARB_texture_query_levels extension.
+
+`GL_ARB_shader_clock`
+> Represents the GL_ARB_shader_clock extension.
+
+`GL_ARB_shader_clock64`
+> Represents the GL_ARB_shader_clock64 extension.
+
+`GL_ARB_gpu_shader_int64`
+> Represents the GL_ARB_gpu_shader_int64 extension.
+
+`GL_KHR_memory_scope_semantics`
+> Represents the GL_KHR_memory_scope_semantics extension.
+
+`GL_KHR_shader_subgroup_arithmetic`
+> Represents the GL_KHR_shader_subgroup_arithmetic extension.
+
+`GL_KHR_shader_subgroup_ballot`
+> Represents the GL_KHR_shader_subgroup_ballot extension.
+
+`GL_KHR_shader_subgroup_basic`
+> Represents the GL_KHR_shader_subgroup_basic extension.
+
+`GL_KHR_shader_subgroup_clustered`
+> Represents the GL_KHR_shader_subgroup_clustered extension.
+
+`GL_KHR_shader_subgroup_quad`
+> Represents the GL_KHR_shader_subgroup_quad extension.
+
+`GL_KHR_shader_subgroup_shuffle`
+> Represents the GL_KHR_shader_subgroup_shuffle extension.
+
+`GL_KHR_shader_subgroup_shuffle_relative`
+> Represents the GL_KHR_shader_subgroup_shuffle_relative extension.
+
+`GL_KHR_shader_subgroup_vote`
+> Represents the GL_KHR_shader_subgroup_vote extension.
+
+`GL_NV_compute_shader_derivatives`
+> Represents the GL_NV_compute_shader_derivatives extension.
+
+`GL_NV_fragment_shader_barycentric`
+> Represents the GL_NV_fragment_shader_barycentric extension.
+
+`GL_NV_gpu_shader5`
+> Represents the GL_NV_gpu_shader5 extension.
+
+`GL_NV_ray_tracing`
+> Represents the GL_NV_ray_tracing extension.
+
+`GL_NV_ray_tracing_motion_blur`
+> Represents the GL_NV_ray_tracing_motion_blur extension.
+
+`GL_NV_shader_atomic_fp16_vector`
+> Represents the GL_NV_shader_atomic_fp16_vector extension.
+
+`GL_NV_shader_invocation_reorder`
+> Represents the GL_NV_shader_invocation_reorder extension.
+
+`GL_NV_shader_subgroup_partitioned`
+> Represents the GL_NV_shader_subgroup_partitioned extension.
+
+`GL_NV_shader_texture_footprint`
+> Represents the GL_NV_shader_texture_footprint extension.
+
+Compound Capabilities
+----------------------
+*Capabilities to specify capabilities created by other capabilities (`raytracing`, `meshshading`...)*
+
+`any_target`
+> All code-gen targets
+
+`any_textual_target`
+> All non-asm code-gen targets
+
+`any_gfx_target`
+> All slang-gfx compatible code-gen targets
+
+`any_cpp_target`
+> All "cpp syntax" code-gen targets
+
+`cpp_cuda`
+> CPP and CUDA code-gen targets
+
+`cpp_cuda_spirv`
+> CPP, CUDA and SPIRV code-gen targets
+
+`cpp_cuda_glsl_spirv`
+> CPP, CUDA, GLSL and SPIRV code-gen targets
+
+`cpp_cuda_glsl_hlsl`
+> CPP, CUDA, GLSL, and HLSL code-gen targets
+
+`cpp_cuda_glsl_hlsl_spirv`
+> CPP, CUDA, GLSL, HLSL, and SPIRV code-gen targets
+
+`cpp_cuda_glsl_hlsl_metal_spirv`
+> CPP, CUDA, GLSL, HLSL, Metal and SPIRV code-gen targets
+
+`cpp_cuda_hlsl`
+> CPP, CUDA, and HLSL code-gen targets
+
+`cpp_cuda_hlsl_spirv`
+> CPP, CUDA, HLSL, and SPIRV code-gen targets
+
+`cpp_cuda_hlsl_metal_spirv`
+> CPP, CUDA, HLSL, Metal, and SPIRV code-gen targets
+
+`cpp_glsl`
+> CPP, and GLSL code-gen targets
+
+`cpp_glsl_hlsl_spirv`
+> CPP, GLSL, HLSL, and SPIRV code-gen targets
+
+`cpp_glsl_hlsl_metal_spirv`
+> CPP, GLSL, HLSL, Metal, and SPIRV code-gen targets
+
+`cpp_hlsl`
+> CPP, and HLSL code-gen targets
+
+`cuda_glsl_hlsl`
+> CUDA, GLSL, and HLSL code-gen targets
+
+`cuda_hlsl_metal_spirv`
+> CUDA, HLSL, Metal, and SPIRV code-gen targets
+
+`cuda_glsl_hlsl_spirv`
+> CUDA, GLSL, HLSL, and SPIRV code-gen targets
+
+`cuda_glsl_hlsl_metal_spirv`
+> CUDA, GLSL, HLSL, Metal, and SPIRV code-gen targets
+
+`cuda_glsl_spirv`
+> CUDA, GLSL, and SPIRV code-gen targets
+
+`cuda_glsl_metal_spirv`
+> CUDA, GLSL, Metal, and SPIRV code-gen targets
+
+`cuda_hlsl`
+> CUDA, and HLSL code-gen targets
+
+`cuda_hlsl_spirv`
+> CUDA, HLSL, SPIRV code-gen targets
+
+`glsl_hlsl_spirv`
+> GLSL, HLSL, and SPIRV code-gen targets
+
+`glsl_hlsl_metal_spirv`
+> GLSL, HLSL, Metal, and SPIRV code-gen targets
+
+`glsl_metal_spirv`
+> GLSL, Metal, and SPIRV code-gen targets
+
+`glsl_spirv`
+> GLSL, and SPIRV code-gen targets
+
+`hlsl_spirv`
+> HLSL, and SPIRV code-gen targets
+
+`nvapi`
+> NVAPI capability for HLSL
+
+`raytracing`
+> Capabilities needed for minimal raytracing support
+
+`ser`
+> Capabilities needed for shader-execution-reordering
+
+`motionblur`
+> Capabilities needed for raytracing-motionblur
+
+`rayquery`
+> Capabilities needed for compute-shader rayquery
+
+`raytracing_motionblur`
+> Capabilities needed for compute-shader rayquery and motion-blur
+
+`ser_motion`
+> Capabilities needed for shader-execution-reordering and motion-blur
+
+`shaderclock`
+> Capabilities needed for realtime clocks
+
+`fragmentshaderinterlock`
+> Capabilities needed for interlocked-fragment operations
+
+`atomic64`
+> Capabilities needed for int64/uint64 atomic operations
+
+`atomicfloat`
+> Capabilities needed to use GLSL-tier-1 float-atomic operations
+
+`atomicfloat2`
+> Capabilities needed to use GLSL-tier-2 float-atomic operations
+
+`fragmentshaderbarycentric`
+> Capabilities needed to use fragment-shader-barycentric's
+
+`shadermemorycontrol`
+> (gfx targets) Capabilities needed to use memory barriers
+
+`waveprefix`
+> Capabilities needed to use HLSL tier wave operations
+
+`bufferreference`
+> Capabilities needed to use GLSL buffer-reference's
+
+`bufferreference_int64`
+> Capabilities needed to use GLSL buffer-reference's with int64
+
+`any_stage`
+> Collection of all shader stages
+
+`amplification_mesh`
+> Collection of shader stages
+
+`raytracing_stages`
+> Collection of shader stages
+
+`anyhit_closesthit`
+> Collection of shader stages
+
+`raygen_closesthit_miss`
+> Collection of shader stages
+
+`anyhit_closesthit_intersection`
+> Collection of shader stages
+
+`anyhit_closesthit_intersection_miss`
+> Collection of shader stages
+
+`raygen_closesthit_miss_callable`
+> Collection of shader stages
+
+`compute_tesscontrol_tesseval`
+> Collection of shader stages
+
+`compute_fragment`
+> Collection of shader stages
+
+`compute_fragment_geometry_vertex`
+> Collection of shader stages
+
+`domain_hull`
+> Collection of shader stages
+
+`raytracingstages_fragment`
+> Collection of shader stages
+
+`raytracingstages_compute`
+> Collection of shader stages
+
+`raytracingstages_compute_amplification_mesh`
+> Collection of shader stages
+
+`raytracingstages_compute_fragment`
+> Collection of shader stages
+
+`raytracingstages_compute_fragment_geometry_vertex`
+> Collection of shader stages
+
+`meshshading`
+> Ccapabilities required to use mesh shading features
+
+`shadermemorycontrol_compute`
+> (gfx targets) Capabilities required to use memory barriers that only work for raytracing & compute shader stages
+
+`subpass`
+> Capabilities required to use Subpass-Input's
+
+`appendstructuredbuffer`
+> Capabilities required to use AppendStructuredBuffer
+
+`atomic_hlsl`
+> (hlsl only) Capabilities required to use hlsl atomic operations
+
+`atomic_hlsl_nvapi`
+> (hlsl only) Capabilities required to use hlsl NVAPI atomics
+
+`atomic_hlsl_sm_6_6`
+> (hlsl only) Capabilities required to use hlsl sm_6_6 atomics
+
+`byteaddressbuffer`
+> Capabilities required to use ByteAddressBuffer
+
+`byteaddressbuffer_rw`
+> Capabilities required to use RWByteAddressBuffer
+
+`consumestructuredbuffer`
+> Capabilities required to use ConsumeStructuredBuffer
+
+`structuredbuffer`
+> Capabilities required to use StructuredBuffer
+
+`structuredbuffer_rw`
+> Capabilities required to use RWStructuredBuffer
+
+`fragmentprocessing`
+> Capabilities required to use fragment derivative operations (without GLSL derivativecontrol)
+
+`fragmentprocessing_derivativecontrol`
+> Capabilities required to use fragment derivative operations (with GLSL derivativecontrol)
+
+`getattributeatvertex`
+> Capabilities required to use 'getAttributeAtVertex'
+
+`memorybarrier`
+> Capabilities required to use sm_5_0 style memory barriers
+
+`texture_sm_4_0`
+> Capabilities required to use sm_4_0 texture operations
+
+`texture_sm_4_1`
+> Capabilities required to use sm_4_1 texture operations
+
+`texture_sm_4_1_samplerless`
+> Capabilities required to use sm_4_1 samplerless texture operations
+
+`texture_sm_4_1_compute_fragment`
+> Capabilities required to use 'compute/fragment shader only' texture operations.
+> We do not require 'compute'/'fragment' shader capabilities since this seems to be incorrect behavior despite what official documentation says.
+
+`texture_sm_4_0_fragment`
+> Capabilities required to use 'fragment shader only' texture operations
+
+`texture_sm_4_1_clamp_fragment`
+> Capabilities required to use 'fragment shader only' texture clamp operations
+
+`texture_sm_4_1_vertex_fragment_geometry`
+> Capabilities required to use 'fragment/geometry shader only' texture clamp operations
+
+`texture_gather`
+> Capabilities required to use 'vertex/fragment/geometry shader only' texture gather operations
+
+`image_samples`
+> Capabilities required to query image (RWTexture) sample info
+
+`image_size`
+> Capabilities required to query image (RWTexture) size info
+
+`texture_size`
+> Capabilities required to query texture sample info
+
+`texture_querylod`
+> Capabilities required to query texture LOD info
+
+`texture_querylevels`
+> Capabilities required to query texture level info
+
+`texture_shadowlod`
+> Capabilities required to query shadow texture lod info
+
+`atomic_glsl_float1`
+> (GLSL/SPIRV) Capabilities required to use GLSL-tier-1 float-atomic operations
+
+`atomic_glsl_float2`
+> (GLSL/SPIRV) Capabilities required to use GLSL-tier-2 float-atomic operations
+
+`atomic_glsl_halfvec`
+> (GLSL/SPIRV) Capabilities required to use NVAPI GLSL-fp16 float-atomic operations
+
+`atomic_glsl`
+> (GLSL/SPIRV) Capabilities required to use GLSL-400 atomic operations
+
+`atomic_glsl_int64`
+> (GLSL/SPIRV) Capabilities required to use int64/uint64 atomic operations
+
+`image_loadstore`
+> (GLSL/SPIRV) Capabilities required to use image load/image store operations
+
+`nonuniformqualifier`
+> Capabilities required to use NonUniform qualifier
+
+`printf`
+> Capabilities required to use 'printf'
+
+`texturefootprint`
+> Capabilities required to use basic TextureFootprint operations
+
+`texturefootprintclamp`
+> Capabilities required to use TextureFootprint clamp operations
+
+`shader5_sm_4_0`
+> Capabilities required to use sm_4_0 features apart of GL_ARB_gpu_shader5
+
+`shader5_sm_5_0`
+> Capabilities required to use sm_5_0 features apart of GL_ARB_gpu_shader5
+
+`subgroup_basic`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_basic'
+
+`subgroup_ballot`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_ballot'
+
+`subgroup_ballot_activemask`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_ballot_activemask'
+
+`subgroup_basic_ballot`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_basic_ballot'
+
+`subgroup_vote`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_vote'
+
+`shaderinvocationgroup`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_vote'
+
+`subgroup_arithmetic`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_arithmetic'
+
+`subgroup_shuffle`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_shuffle'
+
+`subgroup_shufflerelative`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_shufle_relative'
+
+`subgroup_clustered`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_clustered'
+
+`subgroup_quad`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_quad'
+
+`subgroup_partitioned`
+> Capabilities required to use GLSL-style subgroup operations 'subgroup_partitioned'
+
+`atomic_glsl_hlsl_nvapi_cuda_metal_float1`
+> (All implemented targets) Capabilities required to use atomic operations of GLSL tier-1 float atomics
+
+`atomic_glsl_hlsl_nvapi_cuda5_int64`
+> (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_5 tier atomics)
+
+`atomic_glsl_hlsl_nvapi_cuda6_int64`
+> (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_6 tier atomics)
+
+`atomic_glsl_hlsl_nvapi_cuda9_int64`
+> (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_9 tier atomics)
+
+`atomic_glsl_hlsl_cuda_metal`
+> (All implemented targets) Capabilities required to use atomic operations
+
+`atomic_glsl_hlsl_cuda9_int64`
+> (All implemented targets) Capabilities required to use atomic operations (cuda_sm_9 tier atomics)
+
+`helper_lane`
+> Capabilities required to enable helper-lane demotion
+
+`breakpoint`
+> Capabilities required to enable shader breakpoints
+
+`raytracing_allstages`
+> Collection of capabilities for raytracing with all raytracing stages.
+
+`raytracing_anyhit`
+> Collection of capabilities for raytracing with the shader stage of anyhit.
+
+`raytracing_intersection`
+> Collection of capabilities for raytracing with the shader stage of intersection.
+
+`raytracing_anyhit_closesthit`
+> Collection of capabilities for raytracing with the shader stages of anyhit and closesthit.
+
+`raytracing_anyhit_closesthit_intersection`
+> Collection of capabilities for raytracing with the shader stages of anyhit, closesthit, and intersection.
+
+`raytracing_raygen_closesthit_miss`
+> Collection of capabilities for raytracing with the shader stages of raygen, closesthit, and miss.
+
+`raytracing_anyhit_closesthit_intersection_miss`
+> Collection of capabilities for raytracing with the shader stages of anyhit, closesthit, intersection, and miss.
+
+`raytracing_raygen_closesthit_miss_callable`
+> Collection of capabilities for raytracing the shader stages of raygen, closesthit, miss, and callable.
+
+`raytracing_position`
+> Collection of capabilities for raytracing + ray_tracing_position_fetch and the shader stages of anyhit and closesthit.
+
+`raytracing_motionblur_anyhit_closesthit_intersection_miss`
+> Collection of capabilities for raytracing + motion blur and the shader stages of anyhit, closesthit, intersection, and miss.
+
+`raytracing_motionblur_raygen_closesthit_miss`
+> Collection of capabilities for raytracing + motion blur and the shader stages of raygen, closesthit, and miss.
+
+`rayquery_position`
+> Collection of capabilities for rayquery + ray_tracing_position_fetch.
+
+`ser_raygen`
+> Collection of capabilities for raytracing + shader execution reordering and the shader stage of raygen.
+
+`ser_raygen_closesthit_miss`
+> Collection of capabilities for raytracing + shader execution reordering and the shader stages of raygen, closesthit, and miss.
+
+`ser_any_closesthit_intersection_miss`
+> Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit, closesthit, intersection, and miss.
+
+`ser_anyhit_closesthit_intersection`
+> Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit, closesthit, and intersection.
+
+`ser_anyhit_closesthit`
+> Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit and closesthit.
+
+`ser_motion_raygen_closesthit_miss`
+> Collection of capabilities for raytracing + motion blur + shader execution reordering and the shader stages of raygen, closesthit, and miss.
+
+`ser_motion_raygen`
+> Collection of capabilities for raytracing raytracing + motion blur + shader execution reordering and the shader stage of raygen.
+
+Other
+----------------------
+*Capabilities which may be deprecated*
+
+`SPIRV_1_0`
+> Use `spirv_1_0` instead
+
+`SPIRV_1_1`
+> Use `spirv_1_1` instead
+
+`SPIRV_1_2`
+> Use `spirv_1_2` instead
+
+`SPIRV_1_3`
+> Use `spirv_1_3` instead
+
+`SPIRV_1_4`
+> Use `spirv_1_4` instead
+
+`SPIRV_1_5`
+> Use `spirv_1_5` instead
+
+`SPIRV_1_6`
+> Use `spirv_1_6` instead
+
+`DX_4_0`
+> Use `sm_4_0` instead
+
+`DX_4_1`
+> Use `sm_4_1` instead
+
+`DX_5_0`
+> Use `sm_5_0` instead
+
+`DX_5_1`
+> Use `sm_5_1` instead
+
+`DX_6_0`
+> Use `sm_6_0` instead
+
+`DX_6_1`
+> Use `sm_6_1` instead
+
+`DX_6_2`
+> Use `sm_6_2` instead
+
+`DX_6_3`
+> Use `sm_6_3` instead
+
+`DX_6_4`
+> Use `sm_6_4` instead
+
+`DX_6_5`
+> Use `sm_6_5` instead
+
+`DX_6_6`
+> Use `sm_6_6` instead
+
+`DX_6_7`
+> Use `sm_6_7` instead
+
+`GLSL_410_SPIRV_1_0`
+> User should not use this capability
+
+`GLSL_420_SPIRV_1_0`
+> User should not use this capability
+
+`GLSL_430_SPIRV_1_0`
+> User should not use this capability
+
+`METAL_2_3`
+> Use `metallib_2_3` instead
+
+`METAL_2_4`
+> Use `metallib_2_4` instead
+
+`METAL_3_0`
+> Use `metallib_3_0` instead
+
+`METAL_3_1`
+> Use `metallib_3_1` instead
+
+`GLSL_430_SPIRV_1_0_compute`
+> User should not use this capability
+
+`all`
+> User should not use this capability
diff --git a/docs/user-guide/a3-reference.md b/docs/user-guide/a3-reference.md
new file mode 100644
index 000000000..da9d443c9
--- /dev/null
+++ b/docs/user-guide/a3-reference.md
@@ -0,0 +1,11 @@
+---
+layout: user-guide
+permalink: /user-guide/reference
+---
+
+Reference
+============================
+
+In this chapter:
+1. [Reference for all Capability Profiles](a3-01-Reference-Capability-Profiles)
+2. [Reference for all Capability Atoms](a3-02-Reference-Capability-Atoms)
\ No newline at end of file
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index c3c001d56..e6c75b1f1 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -216,6 +216,22 @@
 </li>
 </ul>
 </li>
+<li data-link="reference"><span>Reference</span>
+<ul class="toc_list">
+<li data-link="a3-01-reference-capability-profiles"><span>Capability Profiles</span>
+</li>
+<li data-link="a3-02-reference-capability-atoms"><span>Capability Atoms</span>
+<ul class="toc_list">
+<li data-link="a3-02-reference-capability-atoms#targets"><span>Targets</span></li>
+<li data-link="a3-02-reference-capability-atoms#stages"><span>Stages</span></li>
+<li data-link="a3-02-reference-capability-atoms#versions"><span>Versions</span></li>
+<li data-link="a3-02-reference-capability-atoms#extensions"><span>Extensions</span></li>
+<li data-link="a3-02-reference-capability-atoms#compound-capabilities"><span>Compound Capabilities</span></li>
+<li data-link="a3-02-reference-capability-atoms#other"><span>Other</span></li>
+</ul>
+</li>
+</ul>
+</li>
 </ul>
 </li>
 </ul>
\ No newline at end of file
diff --git a/source/slang/slang-capabilities.capdef b/source/slang/slang-capabilities.capdef
index de44c98a5..a173a332f 100644
--- a/source/slang/slang-capabilities.capdef
+++ b/source/slang/slang-capabilities.capdef
@@ -38,43 +38,115 @@
 
 // - `alias`: this defines an alias and does not introduce actual atoms.
 
-// Several capabilities represent the target formats in which we generate code.
-// Because we can only generate code in one format at a time, all of these are
-// marked as conflicting with one another along the `TargetFormat` axis.
+// How auto-doc works (automatic filling of `a3-02-reference-capability-atoms.md`):
 //
-// Note: We are only including here the source code formats we initially generate
-// code in and not the formats that code might be translated into "downstream."
-// Trying to figure out how to integrate both kinds of formats into our capability
-// system will be an interesting challenge (e.g., can we compile code for `hlsl+spirv`
-// and for `glsl+spirv` or even just for `spirv`, and how should all of those impact
-// overloading).
+// 1. `def`/`alias` are considered 'documentable atoms'
 //
+// 2. Any successive lines of `///` before a 'documentable atom' is assigned as a
+//    doc-comment for the 'documentable atom', for example:
+//
+//    a. "my comment" will be associated with `textualTarget`
+//      ```
+//      /// my comment
+//      def textualTarget; 
+//      ```
+//
+//    b. "" will be associated with `textualTarget`
+//      ```
+//      /// my comment
+//      //
+//      def textualTarget; 
+//      ```
+//
+//    c. "my comment\n additional info" will be associated with `textualTarget`
+//      ```
+//      /// my comment
+//      /// additional info
+//      def textualTarget; 
+//      ```
+//
+// 3. If `[GROUP]` is found apart of a `///[GROUP]` string, this is treated as a "header group".
+//    Only these "header groups" are allowed: [Target] [Stage] [EXT] [Version] [Compound] [Other].
+//    Example(s) are provided below:
+//
+//    a. `textualTarget` will be emitted under header 'Target' with text "my comment"
+//      ```
+//      /// [Target]
+//      /// my comment
+//      def textualTarget; 
+//      ```
+// 4. All 'documentable atoms' must a documentation comment assigned to them. `[GROUP]` does not count as a documentation comment.
+
+/// Represents a non-assembly code generation target.
+/// [Target]
 def textualTarget;
 
 abstract target;
+
+/// Represents the HLSL code generation target.
+/// [Target]
 def hlsl : target + textualTarget;
+
+/// Represents the GLSL code generation target.
+/// [Target]
 def glsl : target + textualTarget;
+
+/// Represents the C programming language code generation target.
+/// [Target]
 def c : target + textualTarget;
+
+/// Represents the C++ programming language code generation target.
+/// [Target]
 def cpp : target + textualTarget;
+
+/// Represents the CUDA code generation target.
+/// [Target]
 def cuda : target + textualTarget;
+
+/// Represents the Metal programming language code generation target.
+/// [Target]
 def metal : target + textualTarget;
+
+/// Represents the SPIR-V code generation target.
+/// [Target]
 def spirv : target;
 
-// Capabilities that stand for target spirv version for GLSL backend.
-// These are not compilation targets. We will convert `_spirv_*`->`glsl_spirv_*` during a compile. 
+// Capabilities that stand for target SPIR-V versions for the GLSL backend.
+// These are not compilation targets. We will convert `_spirv_*` to `glsl_spirv_*` during compilation.
+
+/// Represents SPIR-V 1.0 through glslang.
+/// [Version]
 def glsl_spirv_1_0 : glsl;
+
+/// Represents SPIR-V 1.1 through glslang.
+/// [Version]
 def glsl_spirv_1_1 : glsl_spirv_1_0;
+
+/// Represents SPIR-V 1.2 through glslang.
+/// [Version]
 def glsl_spirv_1_2 : glsl_spirv_1_1;
+
+/// Represents SPIR-V 1.3 through glslang.
+/// [Version]
 def glsl_spirv_1_3 : glsl_spirv_1_2;
+
+/// Represents SPIR-V 1.4 through glslang.
+/// [Version]
 def glsl_spirv_1_4 : glsl_spirv_1_3;
+
+/// Represents SPIR-V 1.5 through glslang.
+/// [Version]
 def glsl_spirv_1_5 : glsl_spirv_1_4;
+
+/// Represents SPIR-V 1.6 through glslang.
+/// [Version]
 def glsl_spirv_1_6 : glsl_spirv_1_5;
 
 // We have multiple capabilities for the various SPIR-V versions,
 // arranged so that they inherit from one another to represent which versions
 // provide a super-set of the features of earlier ones (e.g., SPIR-V 1.4 is
 // expressed as inheriting from SPIR-V 1.3).
-//
+
 def _spirv_1_0 : spirv;
 def _spirv_1_1 : _spirv_1_0;
 def _spirv_1_2 : _spirv_1_1;
@@ -96,14 +168,30 @@ def _GLSL_440 : _GLSL_430;
 def _GLSL_450 : _GLSL_440;
 def _GLSL_460 : _GLSL_450;
 
-// metal versions
+// Metal versions
+
+/// Represents MetalLib 2.3.
+/// [Version]
 def metallib_2_3 : metal;
+
+/// Represents MetalLib 2.4.
+/// [Version]
 def metallib_2_4 : metallib_2_3;
+
+/// Represents MetalLib 3.0.
+/// [Version]
 def metallib_3_0 : metallib_2_4;
+
+/// Represents MetalLib 3.1.
+/// [Version]
 def metallib_3_1 : metallib_3_0;
+
+/// Represents the latest MetalLib version.
+/// [Version]
 alias metallib_latest = metallib_3_1;
 
-// hlsl versions
+// HLSL versions
+
 def _sm_4_0 : hlsl;
 def _sm_4_1 : _sm_4_0;
 def _sm_5_0 : _sm_4_1;
@@ -117,11 +205,16 @@ def _sm_6_5 : _sm_6_4;
 def _sm_6_6 : _sm_6_5;
 def _sm_6_7 : _sm_6_6;
 
+/// Represents HLSL NVAPI support.
+/// [Version]
 def hlsl_nvapi : hlsl;
 
+/// Represents capabilities required for DXIL Library compilation.
+/// [Version]
 alias dxil_lib = _sm_6_3;
 
-// cuda versions
+// CUDA versions
+
 def _cuda_sm_1_0 : cuda;
 def _cuda_sm_2_0 : _cuda_sm_1_0;
 def _cuda_sm_3_0 : _cuda_sm_2_0;
@@ -133,46 +226,156 @@ def _cuda_sm_7_0 : _cuda_sm_6_0;
 def _cuda_sm_8_0 : _cuda_sm_7_0;
 def _cuda_sm_9_0 : _cuda_sm_8_0;
 
+/// All code-gen targets
+/// [Compound]
 alias any_target = hlsl | metal | glsl | c | cpp | cuda | spirv;
+
+/// All non-asm code-gen targets
+/// [Compound]
 alias any_textual_target = hlsl | metal | glsl | c | cpp | cuda;
+
+/// All slang-gfx compatible code-gen targets
+/// [Compound]
 alias any_gfx_target = hlsl | metal | glsl | spirv;
+
+/// All "cpp syntax" code-gen targets
+/// [Compound]
 alias any_cpp_target = cpp | cuda;
 
+/// CPP and CUDA code-gen targets
+/// [Compound]
 alias cpp_cuda = cpp | cuda;
+
+/// CPP, CUDA and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_spirv = cpp | cuda | spirv;
+
+/// CPP, CUDA, GLSL and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_glsl_spirv = cpp | cuda | glsl | spirv;
+
+/// CPP, CUDA, GLSL, and HLSL code-gen targets
+/// [Compound]
 alias cpp_cuda_glsl_hlsl = cpp | cuda | glsl | hlsl;
+
+/// CPP, CUDA, GLSL, HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_glsl_hlsl_spirv = cpp | cuda | glsl | hlsl | spirv;
+
+/// CPP, CUDA, GLSL, HLSL, Metal and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_glsl_hlsl_metal_spirv = cpp | cuda | glsl | hlsl | metal | spirv;
+
+/// CPP, CUDA, and HLSL code-gen targets
+/// [Compound]
 alias cpp_cuda_hlsl = cpp | cuda | hlsl;
+
+/// CPP, CUDA, HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_hlsl_spirv = cpp | cuda | hlsl | spirv;
+
+/// CPP, CUDA, HLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias cpp_cuda_hlsl_metal_spirv = cpp | cuda | hlsl | metal | spirv;
+
+/// CPP, and GLSL code-gen targets
+/// [Compound]
 alias cpp_glsl = cpp | glsl;
+
+/// CPP, GLSL, HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias cpp_glsl_hlsl_spirv = cpp | glsl | hlsl | spirv;
+
+/// CPP, GLSL, HLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias cpp_glsl_hlsl_metal_spirv = cpp | glsl | hlsl | metal | spirv;
+
+/// CPP, and HLSL code-gen targets
+/// [Compound]
 alias cpp_hlsl = cpp | hlsl;
+
+/// CUDA, GLSL, and HLSL code-gen targets
+/// [Compound]
 alias cuda_glsl_hlsl = cuda | glsl | hlsl;
+
+/// CUDA, HLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias cuda_hlsl_metal_spirv = cuda | hlsl | metal | spirv;
+
+/// CUDA, GLSL, HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias cuda_glsl_hlsl_spirv = cuda | glsl | hlsl | spirv;
+
+/// CUDA, GLSL, HLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias cuda_glsl_hlsl_metal_spirv = cuda | glsl | hlsl | metal | spirv;
+
+/// CUDA, GLSL, and SPIRV code-gen targets
+/// [Compound]
 alias cuda_glsl_spirv = cuda | glsl | spirv;
+
+/// CUDA, GLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias cuda_glsl_metal_spirv = cuda | glsl | metal | spirv;
+
+/// CUDA, and HLSL code-gen targets
+/// [Compound]
 alias cuda_hlsl = cuda | hlsl;
+
+/// CUDA, HLSL, SPIRV code-gen targets
+/// [Compound]
 alias cuda_hlsl_spirv = cuda | hlsl | spirv;
+
+/// GLSL, HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias glsl_hlsl_spirv = glsl | hlsl | spirv;
+
+/// GLSL, HLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias glsl_hlsl_metal_spirv = glsl | hlsl | metal | spirv;
+
+/// GLSL, Metal, and SPIRV code-gen targets
+/// [Compound]
 alias glsl_metal_spirv = glsl | metal | spirv;
+
+/// GLSL, and SPIRV code-gen targets
+/// [Compound]
 alias glsl_spirv = glsl | spirv;
+
+/// HLSL, and SPIRV code-gen targets
+/// [Compound]
 alias hlsl_spirv = hlsl | spirv;
 
+// stages
+//
 abstract stage;
+
+/// Vertex shader stage
+/// [Stage]
 def vertex : stage;
+
+/// Fragment shader stage
+/// [Stage]
 def fragment : stage;
+
+/// Compute shader stage
+/// [Stage]
 def compute : stage;
+
+/// Hull shader stage
+/// [Stage]
 def hull : stage;
+
+/// Domain shader stage
+/// [Stage]
 def domain : stage;
+
+/// Geometry shader stage
+/// [Stage]
 def geometry : stage;
+
 def _raygen : stage;
+alias _raygeneration = _raygen;
 def _intersection : stage;
 def _anyhit : stage;
 def _closesthit: stage;
@@ -181,66 +384,222 @@ def _miss : stage;
 def _mesh : stage;
 def _amplification : stage;
 
-// SPIRV extensions.
+// SPIRV extensions
 
+/// Represents the SPIR-V extension for fragment shader interlock operations.
+/// [EXT]
 def SPV_EXT_fragment_shader_interlock : _spirv_1_0;
+
+/// Represents the SPIR-V extension for physical storage buffer.
+/// [EXT]
 def SPV_EXT_physical_storage_buffer : _spirv_1_3;
+
+/// Represents the SPIR-V extension for SPV_EXT_fragment_fully_covered.
+/// [EXT]
 def SPV_EXT_fragment_fully_covered : _spirv_1_0;
+
+/// Represents the SPIR-V extension for descriptor indexing.
+/// [EXT]
 def SPV_EXT_descriptor_indexing : _spirv_1_0;
+
+/// Represents the SPIR-V extension for atomic float add operations.
+/// [EXT]
 def SPV_EXT_shader_atomic_float_add : _spirv_1_0;
+
+/// Represents the SPIR-V extension for atomic float16 add operations.
+/// [EXT]
 def SPV_EXT_shader_atomic_float16_add : SPV_EXT_shader_atomic_float_add;
+
+/// Represents the SPIR-V extension for atomic float min/max operations.
+/// [EXT]
 def SPV_EXT_shader_atomic_float_min_max : _spirv_1_0;
+
+/// Represents the SPIR-V extension for mesh shaders.
+/// [EXT]
 def SPV_EXT_mesh_shader : _spirv_1_4;
+
+/// Represents the SPIR-V extension for demoting to helper invocation.
+/// [EXT]
 def SPV_EXT_demote_to_helper_invocation : _spirv_1_4;
 
+/// Represents the SPIR-V extension for fragment shader barycentric.
+/// [EXT]
 def SPV_KHR_fragment_shader_barycentric : _spirv_1_0;
+
+/// Represents the SPIR-V extension for non-semantic information.
+/// [EXT]
 def SPV_KHR_non_semantic_info : _spirv_1_0;
+
+/// Represents the SPIR-V extension for ray tracing.
+/// [EXT]
 def SPV_KHR_ray_tracing : _spirv_1_4;
+
+/// Represents the SPIR-V extension for ray queries.
+/// [EXT]
 def SPV_KHR_ray_query : _spirv_1_0;
-def SPV_KHR_ray_tracing_position_fetch : _spirv_1_0; // requires SPV_KHR_ray_query or SPV_KHR_ray_tracing
+
+/// Represents the SPIR-V extension for ray tracing position fetch.
+/// Should be used with either SPV_KHR_ray_query or SPV_KHR_ray_tracing.
+/// [EXT]
+def SPV_KHR_ray_tracing_position_fetch : _spirv_1_0;
+
+/// Represents the SPIR-V extension for shader clock.
+/// [EXT]
 def SPV_KHR_shader_clock : _spirv_1_0;
 
+/// Represents the SPIR-V extension for shader subgroup partitioned.
+/// [EXT]
 def SPV_NV_shader_subgroup_partitioned : _spirv_1_0;
+
+/// Represents the SPIR-V extension for ray tracing motion blur.
+/// [EXT]
 def SPV_NV_ray_tracing_motion_blur : _spirv_1_0;
+
+/// Represents the SPIR-V extension for shader invocation reorder.
+/// Requires SPV_KHR_ray_tracing.
+/// [EXT]
 def SPV_NV_shader_invocation_reorder : _spirv_1_5 + SPV_KHR_ray_tracing;
+
+/// Represents the SPIR-V extension for shader image footprint.
+/// [EXT]
 def SPV_NV_shader_image_footprint : _spirv_1_0;
+
+/// Represents the SPIR-V extension for compute shader derivatives.
+/// [EXT]
 def SPV_NV_compute_shader_derivatives : _spirv_1_0;
 
+/// Represents the SPIR-V extension for SPV_GOOGLE_user_type.
+/// [EXT]
 def SPV_GOOGLE_user_type : _spirv_1_0;
 
 // SPIRV Capabilities.
 
+/// Represents the SPIR-V capability for atomic float 32 add operations.
+/// [EXT]
 def spvAtomicFloat32AddEXT : SPV_EXT_shader_atomic_float_add;
+
+/// Represents the SPIR-V capability for atomic float 16 add operations.
+/// [EXT]
 def spvAtomicFloat16AddEXT : SPV_EXT_shader_atomic_float16_add;
+
+/// Represents the SPIR-V capability for 64-bit integer atomics.
+/// [EXT]
 def spvInt64Atomics : _spirv_1_0;
+
+/// Represents the SPIR-V capability for atomic float 32 min/max operations.
+/// [EXT]
 def spvAtomicFloat32MinMaxEXT : SPV_EXT_shader_atomic_float_min_max;
+
+/// Represents the SPIR-V capability for atomic float 16 min/max operations.
+/// [EXT]
 def spvAtomicFloat16MinMaxEXT : SPV_EXT_shader_atomic_float_min_max;
+
+/// Represents the SPIR-V capability for 'derivative control' operations.
+/// [EXT]
 def spvDerivativeControl : _spirv_1_0;
+
+/// Represents the SPIR-V capability for image query operations.
+/// [EXT]
 def spvImageQuery : _spirv_1_0;
+
+/// Represents the SPIR-V capability for extended image gather operations.
+/// [EXT]
 def spvImageGatherExtended : _spirv_1_0;
+
+/// Represents the SPIR-V capability for sparse residency.
+/// [EXT]
 def spvSparseResidency : _spirv_1_0;
+
+/// Represents the SPIR-V capability for image footprint.
+/// [EXT]
 def spvImageFootprintNV : SPV_NV_shader_image_footprint;
+
+/// Represents the SPIR-V capability for using minimum LOD operations.
+/// [EXT]
 def spvMinLod : _spirv_1_0;
+
+/// Represents the SPIR-V capability for using SPV_EXT_fragment_shader_interlock.
+/// [EXT]
 def spvFragmentShaderPixelInterlockEXT : SPV_EXT_fragment_shader_interlock;
+
+/// Represents the SPIR-V capability for using SPV_KHR_fragment_shader_barycentric.
+/// [EXT]
 def spvFragmentBarycentricKHR : SPV_KHR_fragment_shader_barycentric;
+
+/// Represents the SPIR-V capability for using SPV_EXT_fragment_fully_covered functionality.
+/// [EXT]
 def spvFragmentFullyCoveredEXT : SPV_EXT_fragment_fully_covered;
+
+/// Represents the SPIR-V capability for group non-uniform ballot operations.
+/// [EXT]
 def spvGroupNonUniformBallot : _spirv_1_3;
+
+/// Represents the SPIR-V capability for group non-uniform shuffle operations.
+/// [EXT]
 def spvGroupNonUniformShuffle : _spirv_1_3;
+
+/// Represents the SPIR-V capability for group non-uniform arithmetic operations.
+/// [EXT]
 def spvGroupNonUniformArithmetic : _spirv_1_3;
+
+/// Represents the SPIR-V capability for group non-uniform quad operations.
+/// [EXT]
 def spvGroupNonUniformQuad : _spirv_1_3;
+
+/// Represents the SPIR-V capability for group non-uniform vote operations.
+/// [EXT]
 def spvGroupNonUniformVote : _spirv_1_3;
+
+/// Represents the SPIR-V capability for group non-uniform partitioned operations.
+/// [EXT]
 def spvGroupNonUniformPartitionedNV : _spirv_1_3 + SPV_NV_shader_subgroup_partitioned;
+
+/// Represents the SPIR-V capability for ray tracing motion blur.
+/// [EXT]
 def spvRayTracingMotionBlurNV : SPV_NV_ray_tracing_motion_blur;
+
+/// Represents the SPIR-V capability for mesh shading.
+/// [EXT]
 def spvMeshShadingEXT : SPV_EXT_mesh_shader;
+
+/// Represents the SPIR-V capability for ray tracing.
+/// [EXT]
 def spvRayTracingKHR : SPV_KHR_ray_tracing;
+
+/// Represents the SPIR-V capability for ray tracing position fetch.
+/// [EXT]
 def spvRayTracingPositionFetchKHR : SPV_KHR_ray_tracing_position_fetch + spvRayTracingKHR;
+
+/// Represents the SPIR-V capability for ray query.
+/// [EXT]
 def spvRayQueryKHR : SPV_KHR_ray_query;
+
+/// Represents the SPIR-V capability for ray query position fetch.
+/// [EXT]
 def spvRayQueryPositionFetchKHR : SPV_KHR_ray_tracing_position_fetch + spvRayQueryKHR;
+
+/// Represents the SPIR-V capability for shader invocation reorder.
+/// [EXT]
 def spvShaderInvocationReorderNV : SPV_NV_shader_invocation_reorder;
+
+/// Represents the SPIR-V capability for shader clock.
+/// [EXT]
 def spvShaderClockKHR : SPV_KHR_shader_clock;
+
+/// Represents the SPIR-V capability for non-uniform resource indexing.
+/// [EXT]
 def spvShaderNonUniformEXT : SPV_EXT_descriptor_indexing;
+
+/// Represents the SPIR-V capability for non-uniform resource indexing.
+/// [EXT]
 def spvShaderNonUniform : spvShaderNonUniformEXT;
+
+/// Represents the SPIR-V capability for demoting to helper invocation.
+/// [EXT]
 def spvDemoteToHelperInvocationEXT : SPV_EXT_demote_to_helper_invocation;
+
+/// Represents the SPIR-V capability for demoting to helper invocation.
+/// [EXT]
 def spvDemoteToHelperInvocation : spvDemoteToHelperInvocationEXT;
 
 // The following capabilities all pertain to how ray tracing shaders are translated
@@ -318,170 +677,502 @@ def _GL_NV_shader_subgroup_partitioned : _GLSL_140;
 def _GL_NV_shader_texture_footprint : _GLSL_450;
 
 // GLSL extension and SPV extension associations.
+
+/// Represents the GL_EXT_buffer_reference extension.
+/// [EXT]
 alias GL_EXT_buffer_reference = _GL_EXT_buffer_reference | SPV_EXT_physical_storage_buffer;
+
+/// Represents the GL_EXT_buffer_reference_uvec2 extension.
+/// [EXT]
 alias GL_EXT_buffer_reference_uvec2 = _GL_EXT_buffer_reference_uvec2 | _spirv_1_0;
+
+/// Represents the GL_EXT_debug_printf extension.
+/// [EXT]
 alias GL_EXT_debug_printf = _GL_EXT_debug_printf | SPV_KHR_non_semantic_info;
+
+/// Represents the GL_EXT_demote_to_helper_invocation extension.
+/// [EXT]
 alias GL_EXT_demote_to_helper_invocation = _GL_EXT_demote_to_helper_invocation | spvDemoteToHelperInvocationEXT;
+
+/// Represents the GL_EXT_fragment_shader_barycentric extension.
+/// [EXT]
 alias GL_EXT_fragment_shader_barycentric = _GL_EXT_fragment_shader_barycentric | spvFragmentBarycentricKHR;
+
+/// Represents the GL_EXT_mesh_shader extension.
+/// [EXT]
 alias GL_EXT_mesh_shader = _GL_EXT_mesh_shader | spvMeshShadingEXT;
+
+/// Represents the GL_EXT_nonuniform_qualifier extension.
+/// [EXT]
 alias GL_EXT_nonuniform_qualifier = _GL_EXT_nonuniform_qualifier | spvShaderNonUniformEXT;
+
+/// Represents the GL_EXT_ray_query extension.
+/// [EXT]
 alias GL_EXT_ray_query = _GL_EXT_ray_query | spvRayQueryKHR;
+
+/// Represents the GL_EXT_ray_tracing extension.
+/// [EXT]
 alias GL_EXT_ray_tracing = _GL_EXT_ray_tracing | spvRayTracingKHR;
+
+/// Represents the GL_EXT_ray_tracing_position_fetch_ray_tracing extension.
+/// [EXT]
 alias GL_EXT_ray_tracing_position_fetch_ray_tracing = _GL_EXT_ray_tracing_position_fetch | spvRayTracingPositionFetchKHR;
+
+/// Represents the GL_EXT_ray_tracing_position_fetch_ray_query extension.
+/// [EXT]
 alias GL_EXT_ray_tracing_position_fetch_ray_query = _GL_EXT_ray_tracing_position_fetch | spvRayQueryPositionFetchKHR;
+
+/// Represents the GL_EXT_ray_tracing_position_fetch extension.
+/// [EXT]
 alias GL_EXT_ray_tracing_position_fetch = GL_EXT_ray_tracing_position_fetch_ray_tracing + GL_EXT_ray_tracing_position_fetch_ray_query;
+
+/// Represents the GL_EXT_samplerless_texture_functions extension.
+/// [EXT]
 alias GL_EXT_samplerless_texture_functions = _GL_EXT_samplerless_texture_functions | _spirv_1_0;
+
+/// Represents the GL_EXT_shader_atomic_float extension.
+/// [EXT]
 alias GL_EXT_shader_atomic_float = _GL_EXT_shader_atomic_float | spvAtomicFloat32AddEXT + spvAtomicFloat32MinMaxEXT;
+
+/// Represents the GL_EXT_shader_atomic_float_min_max extension.
+/// [EXT]
 alias GL_EXT_shader_atomic_float_min_max = _GL_EXT_shader_atomic_float_min_max | spvAtomicFloat32MinMaxEXT + spvAtomicFloat16MinMaxEXT;
+
+/// Represents the GL_EXT_shader_atomic_float2 extension.
+/// [EXT]
 alias GL_EXT_shader_atomic_float2 = _GL_EXT_shader_atomic_float2 | spvAtomicFloat32AddEXT + spvAtomicFloat32MinMaxEXT + spvAtomicFloat16AddEXT + spvAtomicFloat16MinMaxEXT;
+
+/// Represents the GL_EXT_shader_atomic_int64 extension.
+/// [EXT]
 alias GL_EXT_shader_atomic_int64 = _GL_EXT_shader_atomic_int64 | spvInt64Atomics;
+
+/// Represents the GL_EXT_shader_explicit_arithmetic_types_int64 extension.
+/// [EXT]
 alias GL_EXT_shader_explicit_arithmetic_types_int64 = _GL_EXT_shader_explicit_arithmetic_types_int64 | _spirv_1_0;
+
+/// Represents the GL_EXT_shader_image_load_store extension.
+/// [EXT]
 alias GL_EXT_shader_image_load_store = _GL_EXT_shader_image_load_store | _spirv_1_0;
+
+/// Represents the GL_EXT_shader_realtime_clock extension.
+/// [EXT]
 alias GL_EXT_shader_realtime_clock = _GL_EXT_shader_realtime_clock | spvShaderClockKHR;
+
+/// Represents the GL_EXT_texture_query_lod extension.
+/// [EXT]
 alias GL_EXT_texture_query_lod = _GL_EXT_texture_query_lod | spvImageQuery | metal;
+
+/// Represents the GL_EXT_texture_shadow_lod extension.
+/// [EXT]
 alias GL_EXT_texture_shadow_lod = _GL_EXT_texture_shadow_lod | _spirv_1_0;
 
+/// Represents the GL_ARB_derivative_control extension.
+/// [EXT]
 alias GL_ARB_derivative_control = _GL_ARB_derivative_control | spvDerivativeControl;
+
+/// Represents the GL_ARB_fragment_shader_interlock extension.
+/// [EXT]
 alias GL_ARB_fragment_shader_interlock = _GL_ARB_fragment_shader_interlock | spvFragmentShaderPixelInterlockEXT;
+
+/// Represents the GL_ARB_gpu_shader5 extension.
+/// [EXT]
 alias GL_ARB_gpu_shader5 = _GL_ARB_gpu_shader5 | _spirv_1_0;
+
+/// Represents the GL_ARB_shader_image_load_store extension.
+/// [EXT]
 alias GL_ARB_shader_image_load_store = GL_EXT_shader_image_load_store;
+
+/// Represents the GL_ARB_shader_image_size extension.
+/// [EXT]
 alias GL_ARB_shader_image_size = _GL_ARB_shader_image_size | spvImageQuery | metal;
+
+/// Represents the GL_ARB_texture_multisample extension.
+/// [EXT]
 alias GL_ARB_texture_multisample = _GL_ARB_texture_multisample | _spirv_1_0;
+
+/// Represents the GL_ARB_shader_texture_image_samples extension.
+/// [EXT]
 alias GL_ARB_shader_texture_image_samples = _GL_ARB_shader_texture_image_samples | spvImageQuery | metal;
+
+/// Represents the GL_ARB_sparse_texture extension.
+/// [EXT]
 alias GL_ARB_sparse_texture = _GL_ARB_sparse_texture | spvSparseResidency;
+
+/// Represents the GL_ARB_sparse_texture2 extension.
+/// [EXT]
 alias GL_ARB_sparse_texture2 = _GL_ARB_sparse_texture2 | spvSparseResidency;
+
+/// Represents the GL_ARB_sparse_texture_clamp extension.
+/// [EXT]
 alias GL_ARB_sparse_texture_clamp = _GL_ARB_sparse_texture_clamp | spvSparseResidency;
+
+/// Represents the GL_ARB_texture_gather extension.
+/// [EXT]
 alias GL_ARB_texture_gather = _GL_ARB_texture_gather | spvImageGatherExtended | metal;
+
+/// Represents the GL_ARB_texture_query_levels extension.
+/// [EXT]
 alias GL_ARB_texture_query_levels = _GL_ARB_texture_query_levels | spvImageQuery | metal;
+
+/// Represents the GL_ARB_shader_clock extension.
+/// [EXT]
 alias GL_ARB_shader_clock = _GL_ARB_shader_clock | spvShaderClockKHR;
+
+/// Represents the GL_ARB_shader_clock64 extension.
+/// [EXT]
 alias GL_ARB_shader_clock64 = _GL_ARB_shader_clock64 | spvShaderClockKHR;
+
+/// Represents the GL_ARB_gpu_shader_int64 extension.
+/// [EXT]
 alias GL_ARB_gpu_shader_int64 = _GL_ARB_gpu_shader_int64;
 
+/// Represents the GL_KHR_memory_scope_semantics extension.
+/// [EXT]
 alias GL_KHR_memory_scope_semantics = _GL_KHR_memory_scope_semantics | _spirv_1_0;
+
+/// Represents the GL_KHR_shader_subgroup_arithmetic extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_arithmetic = _GL_KHR_shader_subgroup_arithmetic | spvGroupNonUniformArithmetic;
+
+/// Represents the GL_KHR_shader_subgroup_ballot extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_ballot = _GL_KHR_shader_subgroup_ballot | spvGroupNonUniformBallot;
+
+/// Represents the GL_KHR_shader_subgroup_basic extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_basic = _GL_KHR_shader_subgroup_basic | spvGroupNonUniformBallot;
+
+/// Represents the GL_KHR_shader_subgroup_clustered extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_clustered = _GL_KHR_shader_subgroup_clustered | spvGroupNonUniformShuffle;
+
+/// Represents the GL_KHR_shader_subgroup_quad extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_quad = _GL_KHR_shader_subgroup_quad | spvGroupNonUniformQuad;
+
+/// Represents the GL_KHR_shader_subgroup_shuffle extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_shuffle = _GL_KHR_shader_subgroup_shuffle | spvGroupNonUniformShuffle;
+
+/// Represents the GL_KHR_shader_subgroup_shuffle_relative extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_shuffle_relative = _GL_KHR_shader_subgroup_shuffle_relative | spvGroupNonUniformShuffle;
+
+/// Represents the GL_KHR_shader_subgroup_vote extension.
+/// [EXT]
 alias GL_KHR_shader_subgroup_vote = _GL_KHR_shader_subgroup_vote | spvGroupNonUniformVote;
 
+/// Represents the GL_NV_compute_shader_derivatives extension.
+/// [EXT]
 alias GL_NV_compute_shader_derivatives = _GL_NV_compute_shader_derivatives | SPV_NV_compute_shader_derivatives | _sm_6_6;
+
+/// Represents the GL_NV_fragment_shader_barycentric extension.
+/// [EXT]
 alias GL_NV_fragment_shader_barycentric = GL_EXT_fragment_shader_barycentric;
+
+/// Represents the GL_NV_gpu_shader5 extension.
+/// [EXT]
 alias GL_NV_gpu_shader5 = GL_ARB_gpu_shader5;
+
+/// Represents the GL_NV_ray_tracing extension.
+/// [EXT]
 alias GL_NV_ray_tracing = GL_EXT_ray_tracing;
+
+/// Represents the GL_NV_ray_tracing_motion_blur extension.
+/// [EXT]
 alias GL_NV_ray_tracing_motion_blur = _GL_NV_ray_tracing_motion_blur | spvRayTracingMotionBlurNV;
+
+/// Represents the GL_NV_shader_atomic_fp16_vector extension.
+/// [EXT]
 alias GL_NV_shader_atomic_fp16_vector = _GL_NV_shader_atomic_fp16_vector + _GL_NV_gpu_shader5 | _spirv_1_0;
+
+/// Represents the GL_NV_shader_invocation_reorder extension.
+/// [EXT]
 alias GL_NV_shader_invocation_reorder = _GL_NV_shader_invocation_reorder + _GL_EXT_buffer_reference_uvec2 | spvShaderInvocationReorderNV;
+
+/// Represents the GL_NV_shader_subgroup_partitioned extension.
+/// [EXT]
 alias GL_NV_shader_subgroup_partitioned = _GL_NV_shader_subgroup_partitioned | spvGroupNonUniformPartitionedNV;
+
+/// Represents the GL_NV_shader_texture_footprint extension.
+/// [EXT]
 alias GL_NV_shader_texture_footprint = _GL_NV_shader_texture_footprint | spvImageFootprintNV;
 
 // Define feature names not reliant on shader stages
 
+/// NVAPI capability for HLSL
+/// [Compound]
 alias nvapi = hlsl_nvapi;
+
+/// Capabilities needed for minimal raytracing support
+/// [Compound]
 alias raytracing = GL_EXT_ray_tracing | _sm_6_3 | cuda;
+/// Capabilities needed for shader-execution-reordering
+/// [Compound]
 alias ser = raytracing + GL_NV_shader_invocation_reorder | raytracing + hlsl_nvapi | cuda;
+/// Capabilities needed for raytracing-motionblur
+/// [Compound]
 alias motionblur = GL_NV_ray_tracing_motion_blur | _sm_6_3 + hlsl_nvapi | cuda;
+/// Capabilities needed for compute-shader rayquery
+/// [Compound]
 alias rayquery = GL_EXT_ray_query | _sm_6_3;
+/// Capabilities needed for compute-shader rayquery and motion-blur
+/// [Compound]
 alias raytracing_motionblur =  raytracing + motionblur | cuda;
+/// Capabilities needed for shader-execution-reordering and motion-blur
+/// [Compound]
 alias ser_motion = ser + motionblur;
+/// Capabilities needed for realtime clocks
+/// [Compound]
 alias shaderclock = GL_EXT_shader_realtime_clock | hlsl_nvapi | cpp | cuda;
 alias _meshshading = GL_EXT_mesh_shader | _sm_6_5 | metal;
+/// Capabilities needed for interlocked-fragment operations
+/// [Compound]
 alias fragmentshaderinterlock = _GL_ARB_fragment_shader_interlock | hlsl_nvapi | spvFragmentShaderPixelInterlockEXT;
+/// Capabilities needed for int64/uint64 atomic operations
+/// [Compound]
 alias atomic64 = GL_EXT_shader_atomic_int64 | _sm_6_6 | cpp | cuda;
+/// Capabilities needed to use GLSL-tier-1 float-atomic operations
+/// [Compound]
 alias atomicfloat = GL_EXT_shader_atomic_float | _sm_6_0 + hlsl_nvapi | cpp | cuda;
+/// Capabilities needed to use GLSL-tier-2 float-atomic operations
+/// [Compound]
 alias atomicfloat2 = GL_EXT_shader_atomic_float2 | _sm_6_6 + hlsl_nvapi | cpp | cuda;
+/// Capabilities needed to use fragment-shader-barycentric's
+/// [Compound]
 alias fragmentshaderbarycentric = GL_EXT_fragment_shader_barycentric | _sm_6_1;
+///  (gfx targets) Capabilities needed to use memory barriers
+/// [Compound]
 alias shadermemorycontrol = glsl | _spirv_1_0 | _sm_5_0;
+/// Capabilities needed to use HLSL tier wave operations
+/// [Compound]
 alias waveprefix = _sm_6_5 | _cuda_sm_7_0 | GL_KHR_shader_subgroup_arithmetic;
+/// Capabilities needed to use GLSL buffer-reference's
+/// [Compound]
 alias bufferreference = GL_EXT_buffer_reference;
+/// Capabilities needed to use GLSL buffer-reference's with int64
+/// [Compound]
 alias bufferreference_int64 = bufferreference + GL_EXT_shader_explicit_arithmetic_types_int64;
 
-// non-internal shader stages
-
+// Non-internal shader stages
+//
+/// Pixel shader stage
+/// [Stage]
 alias pixel = fragment;
 
+/// Tessellation Control shader stage
+/// [Stage]
 alias tesscontrol = hull;
+
+/// Tessellation Evaluation shader stage
+/// [Stage]
 alias tesseval = domain;
 
-alias _raygeneration = _raygen;
+/// Ray-Generation shader stage & ray-tracing capabilities
+/// [Stage]
 alias raygen = _raygen + raytracing;
+
+/// Ray-Generation shader stage & ray-tracing capabilities
+/// [Stage]
 alias raygeneration = _raygeneration + raytracing;
+
+/// Intersection shader stage & ray-tracing capabilities
+/// [Stage]
 alias intersection = _intersection + raytracing;
+
+/// Any-Hit shader stage & ray-tracing capabilities
+/// [Stage]
 alias anyhit = _anyhit + raytracing;
+
+/// Closest-Hit shader stage & ray-tracing capabilities
+/// [Stage]
 alias closesthit = _closesthit + raytracing;
+
+/// Callable shader stage & ray-tracing capabilities
+/// [Stage]
 alias callable = _callable + raytracing;
+
+/// Ray-Miss shader stage & ray-tracing capabilities
+/// [Stage]
 alias miss = _miss + raytracing;
 
+/// Mesh shader stage & mesh shader capabilities
+/// [Stage]
 alias mesh = _mesh + _meshshading;
+
+/// Amplification shader stage & mesh shader capabilities
+/// [Stage]
 alias amplification = _amplification + _meshshading;
 
 // shader stage groups
-
+/// Collection of all shader stages
+/// [Compound]
 alias any_stage = vertex | fragment | compute | hull | domain | geometry 
                  | raygen | intersection | anyhit | closesthit | miss | mesh
                  | amplification | callable
                  ;
+
+/// Collection of shader stages
+/// [Compound]
 alias amplification_mesh = amplification | mesh;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracing_stages = raygen | intersection | anyhit | closesthit | miss | callable;
+
+/// Collection of shader stages
+/// [Compound]
 alias anyhit_closesthit = anyhit | closesthit;
+
+/// Collection of shader stages
+/// [Compound]
 alias raygen_closesthit_miss = raygen | closesthit | miss;
+
+/// Collection of shader stages
+/// [Compound]
 alias anyhit_closesthit_intersection = anyhit | closesthit | intersection;
+
+/// Collection of shader stages
+/// [Compound]
 alias anyhit_closesthit_intersection_miss = anyhit | closesthit | intersection | miss;
+
+/// Collection of shader stages
+/// [Compound]
 alias raygen_closesthit_miss_callable = raygen | closesthit | miss | callable;
+
+/// Collection of shader stages
+/// [Compound]
 alias compute_tesscontrol_tesseval = compute | tesscontrol | tesseval;
+
+/// Collection of shader stages
+/// [Compound]
 alias compute_fragment = compute | fragment;
+
+/// Collection of shader stages
+/// [Compound]
 alias compute_fragment_geometry_vertex = compute | fragment | geometry | vertex;
+
+/// Collection of shader stages
+/// [Compound]
 alias domain_hull = domain | hull;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracingstages_fragment = raytracing_stages | fragment;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracingstages_compute = raytracing_stages | compute;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracingstages_compute_amplification_mesh = raytracingstages_compute | amplification_mesh;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracingstages_compute_fragment = raytracing_stages | compute_fragment;
+
+/// Collection of shader stages
+/// [Compound]
 alias raytracingstages_compute_fragment_geometry_vertex = raytracing_stages | compute_fragment_geometry_vertex;
 
 // Define feature names reliant on shader stages
 
+/// Ccapabilities required to use mesh shading features
+/// [Compound]
 alias meshshading = amplification_mesh + _meshshading;
 
+/// (gfx targets) Capabilities required to use memory barriers that only work for raytracing & compute shader stages
+/// [Compound]
 alias shadermemorycontrol_compute = raytracingstages_compute + shadermemorycontrol;
+
+/// Capabilities required to use Subpass-Input's
+/// [Compound]
 alias subpass = fragment + _sm_6_0 | fragment + any_gfx_target;
 
 // Define what each shader model means on different targets.
 
-// spirv profile
-
+// SPIR-V profile capabilities
+//
+/// Represents SPIR-V 1.0 version.
+/// [Version]
 alias spirv_1_0 = _spirv_1_0;
+
+/// Represents SPIR-V 1.1 version, which includes SPIR-V 1.0.
+/// [Version]
 alias spirv_1_1 = _spirv_1_1
                 | spirv_1_0
                 ;
+
+/// Represents SPIR-V 1.2 version, which includes SPIR-V 1.1.
+/// [Version]
 alias spirv_1_2 = _spirv_1_2
                 | spirv_1_1
                 ;
+
+/// Represents SPIR-V 1.3 version, which includes SPIR-V 1.2.
+/// [Version]
 alias spirv_1_3 = _spirv_1_3
                 | spirv_1_2
                 ;
+
+/// Represents SPIR-V 1.4 version, which includes SPIR-V 1.3.
+/// [Version]
 alias spirv_1_4 = _spirv_1_4
                 | spirv_1_3
                 ;
+
+/// Represents SPIR-V 1.5 version, which includes SPIR-V 1.4 and additional extensions.
+/// [Version]
 alias spirv_1_5 = _spirv_1_5 + GL_EXT_nonuniform_qualifier + GL_EXT_buffer_reference
                 | spirv_1_4
                 ;
+
+/// Represents SPIR-V 1.6 version, which includes SPIR-V 1.5 and additional extensions.
+/// [Version]
 alias spirv_1_6 = _spirv_1_6 + GL_EXT_debug_printf + GL_EXT_demote_to_helper_invocation
                 | spirv_1_5
                 ;
+
+/// Represents the latest SPIR-V version.
+/// [Version]
 alias spirv_latest = _spirv_1_6;
 
+// Aliases for SPIR-V versions
+
+/// Use `spirv_1_0` instead
+/// [Other]
 alias SPIRV_1_0 = spirv_1_0;
+
+/// Use `spirv_1_1` instead
+/// [Other]
 alias SPIRV_1_1 = spirv_1_1;
+
+/// Use `spirv_1_2` instead
+/// [Other]
 alias SPIRV_1_2 = spirv_1_2;
+
+/// Use `spirv_1_3` instead
+/// [Other]
 alias SPIRV_1_3 = spirv_1_3;
+
+/// Use `spirv_1_4` instead
+/// [Other]
 alias SPIRV_1_4 = spirv_1_4;
+
+/// Use `spirv_1_5` instead
+/// [Other]
 alias SPIRV_1_5 = spirv_1_5;
-alias SPIRV_1_6 = spirv_1_6;
 
-// hlsl profile
+/// Use `spirv_1_6` instead
+/// [Other]
+alias SPIRV_1_6 = spirv_1_6;
 
+// HLSL profile capabilities
+//
+/// HLSL shader model 4.0 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_4_0_version = _sm_4_0
              | _GLSL_150
              | spirv_1_0
@@ -489,11 +1180,19 @@ alias sm_4_0_version = _sm_4_0
              | metal
              | cpp
              ;
+
+
+/// HLSL shader model 4.0 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_4_0 = sm_4_0_version
              | SPV_GOOGLE_user_type + spvMinLod
              | GL_ARB_sparse_texture_clamp + GL_EXT_samplerless_texture_functions + GL_EXT_texture_query_lod + GL_EXT_texture_shadow_lod + GL_EXT_debug_printf + GL_ARB_shader_image_size
              ;
 
+/// HLSL shader model 4.1 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_4_1_version = _sm_4_1
              | _GLSL_150
              | spirv_1_0
@@ -501,12 +1200,18 @@ alias sm_4_1_version = _sm_4_1
              | metal
              | cpp
              ;
+/// HLSL shader model 4.1 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_4_1 = sm_4_1_version
              | GL_ARB_texture_gather + GL_ARB_texture_query_levels + GL_ARB_shader_texture_image_samples
              // previous
              | sm_4_0
              ;
 
+/// HLSL shader model 5.0 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_5_0_version = _sm_5_0 
              | _GLSL_330
              | spirv_1_0
@@ -514,6 +1219,9 @@ alias sm_5_0_version = _sm_5_0
              | metal
              | cpp
              ;
+/// HLSL shader model 5.0 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_5_0 = sm_5_0_version
              | GL_KHR_memory_scope_semantics + GL_ARB_gpu_shader5 + GL_ARB_derivative_control
              | spvFragmentFullyCoveredEXT
@@ -521,6 +1229,9 @@ alias sm_5_0 = sm_5_0_version
              | sm_4_1
              ;
 
+/// HLSL shader model 5.1 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_5_1_version = _sm_5_1
              | _GLSL_330
              | spirv_1_0
@@ -528,12 +1239,18 @@ alias sm_5_1_version = _sm_5_1
              | metal
              | cpp
              ;
+/// HLSL shader model 5.1 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_5_1 = sm_5_1_version 
              | GL_EXT_nonuniform_qualifier + GL_ARB_gpu_shader5
              // previous
              | sm_5_0
              ;
 
+/// HLSL shader model 6.0 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_0_version = _sm_6_0 
              | _GLSL_450
              | spirv_1_3
@@ -541,12 +1258,18 @@ alias sm_6_0_version = _sm_6_0
              | metal
              | cpp
              ;
+/// HLSL shader model 6.0 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_0 = sm_6_0_version 
              |  GL_KHR_shader_subgroup_ballot + GL_KHR_shader_subgroup_shuffle + GL_KHR_shader_subgroup_arithmetic + GL_KHR_shader_subgroup_quad + GL_KHR_shader_subgroup_vote
              // previous
              | sm_5_1
              ;
 
+/// HLSL shader model 6.1 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_1_version = _sm_6_1 
              | _GLSL_450 
              | spirv_1_3 
@@ -554,12 +1277,18 @@ alias sm_6_1_version = _sm_6_1
              | metal
              | cpp
              ;
+/// HLSL shader model 6.1 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_1 = sm_6_1_version 
              | GL_EXT_fragment_shader_barycentric 
              // previous
              | sm_6_0
              ;
 
+/// HLSL shader model 6.2 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_2_version = _sm_6_2
              | _GLSL_450
              | spirv_1_3
@@ -567,11 +1296,17 @@ alias sm_6_2_version = _sm_6_2
              | metal
              | cpp
              ;
+/// HLSL shader model 6.2 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_2 = sm_6_2_version
              // previous
              | sm_6_1
              ;
 
+/// HLSL shader model 6.3 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_3_version = _sm_6_3
              | _GLSL_460 
              | spirv_1_4
@@ -579,12 +1314,18 @@ alias sm_6_3_version = _sm_6_3
              | metal
              | cpp
              ;
+/// HLSL shader model 6.3 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_3 = sm_6_3_version
              | GL_EXT_ray_tracing + GL_EXT_ray_tracing_position_fetch_ray_tracing
              // previous
              | sm_6_2
              ;
 
+/// HLSL shader model 6.4 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_4_version = _sm_6_4
              | _GLSL_460
              | spirv_1_4
@@ -592,11 +1333,17 @@ alias sm_6_4_version = _sm_6_4
              | metal
              | cpp
              ;
+/// HLSL shader model 6.4 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_4 = sm_6_4_version
              // previous
              | sm_6_3
              ;
 
+/// HLSL shader model 6.5 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_5_version = _sm_6_5
              | _GLSL_460
              | spirv_1_4
@@ -604,6 +1351,9 @@ alias sm_6_5_version = _sm_6_5
              | metal
              | cpp
              ;
+/// HLSL shader model 6.5 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_5 = sm_6_5_version
              // also requires: GL_NV_shader_subgroup_partitioned
              | GL_EXT_mesh_shader + GL_EXT_ray_query + GL_EXT_ray_tracing_position_fetch_ray_query
@@ -611,6 +1361,9 @@ alias sm_6_5 = sm_6_5_version
              | sm_6_4
              ;
 
+/// HLSL shader model 6.6 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_6_version = _sm_6_6
              | _GLSL_460
              | spirv_1_4
@@ -618,11 +1371,17 @@ alias sm_6_6_version = _sm_6_6
              | metal
              | cpp
              ;
+/// HLSL shader model 6.6 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_6 = sm_6_6_version
              | GL_EXT_shader_atomic_int64 + GL_EXT_shader_atomic_float2 + GL_EXT_shader_atomic_float + _GL_EXT_shader_atomic_float_min_max
              | sm_6_5
              ;
 
+/// HLSL shader model 6.7 and related capabilities of other targets.
+/// Does not include related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_7_version = _sm_6_7
              | _GLSL_460
              | spirv_1_4
@@ -630,25 +1389,65 @@ alias sm_6_7_version = _sm_6_7
              | metal
              | cpp
              ;
+/// HLSL shader model 6.7 and related capabilities of other targets.
+/// Includes related GLSL/SPIRV extensions.
+/// [Version]
 alias sm_6_7 = sm_6_7_version
              | sm_6_6
              ;
 
+/// Use `sm_4_0` instead
+/// [Other]
 alias DX_4_0 = sm_4_0;
+
+/// Use `sm_4_1` instead
+/// [Other]
 alias DX_4_1 = sm_4_1;
+
+/// Use `sm_5_0` instead
+/// [Other]
 alias DX_5_0 = sm_5_0;
+
+/// Use `sm_5_1` instead
+/// [Other]
 alias DX_5_1 = sm_5_1;
+
+/// Use `sm_6_0` instead
+/// [Other]
 alias DX_6_0 = sm_6_0;
+
+/// Use `sm_6_1` instead
+/// [Other]
 alias DX_6_1 = sm_6_1;
+
+/// Use `sm_6_2` instead
+/// [Other]
 alias DX_6_2 = sm_6_2;
+
+/// Use `sm_6_3` instead
+/// [Other]
 alias DX_6_3 = sm_6_3;
+
+/// Use `sm_6_4` instead
+/// [Other]
 alias DX_6_4 = sm_6_4;
+
+/// Use `sm_6_5` instead
+/// [Other]
 alias DX_6_5 = sm_6_5;
+
+/// Use `sm_6_6` instead
+/// [Other]
 alias DX_6_6 = sm_6_6;
-alias DX_6_7 = sm_6_7;
 
-// glsl profile
+/// Use `sm_6_7` instead
+/// [Other]
+alias DX_6_7 = sm_6_7;
 
+// GLSL profile capabilities
+//
+/// GLSL 130 and related capabilities of other targets.
+/// [Version]
 alias GLSL_130 = _GLSL_130
                | _sm_4_0
                | _cuda_sm_2_0
@@ -656,6 +1455,8 @@ alias GLSL_130 = _GLSL_130
                | metal
                | cpp
                ;
+/// GLSL 140 and related capabilities of other targets.
+/// [Version]
 alias GLSL_140 = _GLSL_140
                | _sm_4_1
                | _cuda_sm_2_0
@@ -665,6 +1466,8 @@ alias GLSL_140 = _GLSL_140
                // previous
                | GLSL_130
                ;
+/// GLSL 150 and related capabilities of other targets.
+/// [Version]
 alias GLSL_150 = _GLSL_150
                | _sm_4_1
                | _cuda_sm_2_0
@@ -676,6 +1479,8 @@ alias GLSL_150 = _GLSL_150
                // previous
                | GLSL_140
                ;
+/// GLSL 330 and related capabilities of other targets.
+/// [Version]
 alias GLSL_330 = _GLSL_330
                | _sm_5_0
                | _cuda_sm_6_0
@@ -685,6 +1490,8 @@ alias GLSL_330 = _GLSL_330
                // previous
                | GLSL_150
                ;
+/// GLSL 400 and related capabilities of other targets.
+/// [Version]
 alias GLSL_400 = _GLSL_400
                | _sm_5_1
                | _cuda_sm_6_0
@@ -696,6 +1503,8 @@ alias GLSL_400 = _GLSL_400
                // previous
                | GLSL_330
                ;
+/// GLSL 410 and related capabilities of other targets.
+/// [Version]
 alias GLSL_410 = _GLSL_410
                | _sm_5_1
                | _cuda_sm_6_0
@@ -705,6 +1514,8 @@ alias GLSL_410 = _GLSL_410
                // previous
                | GLSL_400
                ;
+/// GLSL 420 and related capabilities of other targets.
+/// [Version]
 alias GLSL_420 = _GLSL_420
                | _sm_5_1
                | _cuda_sm_6_0
@@ -716,6 +1527,8 @@ alias GLSL_420 = _GLSL_420
                // previous
                | GLSL_410
                ;
+/// GLSL 430 and related capabilities of other targets.
+/// [Version]
 alias GLSL_430 = _GLSL_430
                | _sm_5_1
                | _cuda_sm_6_0
@@ -727,6 +1540,8 @@ alias GLSL_430 = _GLSL_430
                // previous
                | GLSL_420
                ;
+/// GLSL 440 and related capabilities of other targets.
+/// [Version]
 alias GLSL_440 = _GLSL_440
                | _sm_6_0
                | _cuda_sm_6_0
@@ -736,6 +1551,8 @@ alias GLSL_440 = _GLSL_440
                // previous
                | GLSL_430
                ;
+/// GLSL 450 and related capabilities of other targets.
+/// [Version]
 alias GLSL_450 = _GLSL_450 
                | _sm_6_0
                | _cuda_sm_6_0
@@ -747,6 +1564,8 @@ alias GLSL_450 = _GLSL_450
                // previous
                | GLSL_440
                ;
+/// GLSL 460 and related capabilities of other targets.
+/// [Version]
 alias GLSL_460 = _GLSL_460
                | _sm_6_6
                | _cuda_sm_6_0
@@ -757,39 +1576,110 @@ alias GLSL_460 = _GLSL_460
                | GLSL_450
                ;
 
+/// User should not use this capability
+/// [Other]
 alias GLSL_410_SPIRV_1_0 = _GLSL_410 | spirv_1_0;
+
+/// User should not use this capability
+/// [Other]
 alias GLSL_420_SPIRV_1_0 = _GLSL_420 + GLSL_410_SPIRV_1_0 | GLSL_410_SPIRV_1_0;
-alias GLSL_430_SPIRV_1_0 = _GLSL_430 + GLSL_420_SPIRV_1_0 | GLSL_420_SPIRV_1_0;
 
-// cuda profile
+/// User should not use this capability
+/// [Other]
+alias GLSL_430_SPIRV_1_0 = _GLSL_430 + GLSL_420_SPIRV_1_0 | GLSL_420_SPIRV_1_0;
 
+// CUDA profile capabilities
+//
+/// cuda 1.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_1_0 = _cuda_sm_1_0 | sm_4_0;
+
+/// cuda 2.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_2_0 = _cuda_sm_2_0 | sm_4_1;
+
+/// cuda 3.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_3_0 = _cuda_sm_3_0 | sm_6_0;
+
+/// cuda 3.5 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_3_5 = _cuda_sm_3_5 | sm_6_0;
+
+/// cuda 4.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_4_0 = _cuda_sm_4_0 | sm_6_0;
+
+/// cuda 5.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_5_0 = _cuda_sm_5_0 | sm_6_0;
+
+/// cuda 6.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_6_0 = _cuda_sm_6_0 | sm_6_0;
+
+/// cuda 7.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_7_0 = _cuda_sm_7_0 | sm_5_1;
+
+/// cuda 8.0 and related capabilities of other targets.
+/// [Version]
 alias cuda_sm_8_0 = _cuda_sm_8_0 | sm_5_1;
-alias cuda_sm_9_0 = _cuda_sm_9_0 | sm_5_1;
 
-// metal profile
+/// cuda 9.0 and related capabilities of other targets.
+/// [Version]
+alias cuda_sm_9_0 = _cuda_sm_9_0 | sm_5_1;
 
+// Metal profile capabilities
+//
+/// Use `metallib_2_3` instead
+/// [Other]
 alias METAL_2_3 = metallib_2_3;
+
+/// Use `metallib_2_4` instead
+/// [Other]
 alias METAL_2_4 = metallib_2_4;
+
+/// Use `metallib_3_0` instead
+/// [Other]
 alias METAL_3_0 = metallib_3_0;
-alias METAL_3_1 = metallib_3_1;
 
-// Profiles of convenience
+/// Use `metallib_3_1` instead
+/// [Other]
+alias METAL_3_1 = metallib_3_1;
 
+// Capabilities of convenience
+//
+/// Capabilities required to use AppendStructuredBuffer
+/// [Compound]
 alias appendstructuredbuffer = sm_5_0_version;
+/// (hlsl only) Capabilities required to use hlsl atomic operations
+/// [Compound]
 alias atomic_hlsl = _sm_4_0;
+/// (hlsl only) Capabilities required to use hlsl NVAPI atomics 
+/// [Compound]
 alias atomic_hlsl_nvapi = _sm_4_0 + hlsl_nvapi;
+/// (hlsl only) Capabilities required to use hlsl sm_6_6 atomics 
+/// [Compound]
 alias atomic_hlsl_sm_6_6 = _sm_6_6;
+/// Capabilities required to use ByteAddressBuffer 
+/// [Compound]
 alias byteaddressbuffer = sm_4_0_version;
+/// Capabilities required to use RWByteAddressBuffer 
+/// [Compound]
 alias byteaddressbuffer_rw = sm_4_0_version;
+/// Capabilities required to use ConsumeStructuredBuffer 
+/// [Compound]
 alias consumestructuredbuffer = sm_5_0_version;
+/// Capabilities required to use StructuredBuffer
+/// [Compound]
+alias structuredbuffer = sm_4_0_version;
+/// Capabilities required to use RWStructuredBuffer
+/// [Compound]
+alias structuredbuffer_rw = sm_4_0_version;
+
+/// Capabilities required to use fragment derivative operations (without GLSL derivativecontrol)
+/// [Compound]
 alias fragmentprocessing = fragment + _sm_5_0
                          | fragment + glsl_spirv
                          | raytracingstages_compute_amplification_mesh + GL_NV_compute_shader_derivatives
@@ -797,112 +1687,270 @@ alias fragmentprocessing = fragment + _sm_5_0
                          | fragment + cpp
                          | fragment + cuda
                          ;
+/// Capabilities required to use fragment derivative operations (with GLSL derivativecontrol)
+/// [Compound]
 alias fragmentprocessing_derivativecontrol = fragment + _sm_5_0
                                            | fragment + GL_ARB_derivative_control
                                            | raytracingstages_compute_amplification_mesh + GL_NV_compute_shader_derivatives
                                            ;
+/// Capabilities required to use 'getAttributeAtVertex'
+/// [Compound]
 alias getattributeatvertex = fragment + _sm_6_1 | fragment + GL_EXT_fragment_shader_barycentric;
+/// Capabilities required to use sm_5_0 style memory barriers
+/// [Compound]
 alias memorybarrier = sm_5_0_version;
-alias structuredbuffer = sm_4_0_version;
-alias structuredbuffer_rw = sm_4_0_version;
+/// Capabilities required to use sm_4_0 texture operations
+/// [Compound]
 alias texture_sm_4_0 = sm_4_0_version | GL_ARB_sparse_texture_clamp + GL_EXT_texture_query_lod
                      ;
+/// Capabilities required to use sm_4_1 texture operations
+/// [Compound]
 alias texture_sm_4_1 = sm_4_1_version | GL_ARB_sparse_texture_clamp + GL_EXT_texture_query_lod
                      ;
+/// Capabilities required to use sm_4_1 samplerless texture operations
+/// [Compound]
 alias texture_sm_4_1_samplerless = texture_sm_4_1
                               // add samplerless to all targets that need an extension
                               | GL_EXT_samplerless_texture_functions
                               ;
 
-// supposedly works on only limited stages, support all stages for now
+// Supposedly only works for some shader stages, we support all stages for now since this
+// seems wrong.
+/// Capabilities required to use 'compute/fragment shader only' texture operations. 
+/// We do not require 'compute'/'fragment' shader capabilities since this seems to be incorrect behavior despite what official documentation says.
+/// [Compound]
 alias texture_sm_4_1_compute_fragment = texture_sm_4_1;
+/// Capabilities required to use 'fragment shader only' texture operations
+/// [Compound]
 alias texture_sm_4_0_fragment = texture_sm_4_0;
+/// Capabilities required to use 'fragment shader only' texture clamp operations
+/// [Compound]
 alias texture_sm_4_1_clamp_fragment = texture_sm_4_0_fragment | GL_ARB_sparse_texture_clamp;
+/// Capabilities required to use 'fragment/geometry shader only' texture clamp operations
+/// [Compound]
 alias texture_sm_4_1_vertex_fragment_geometry = texture_sm_4_1;
+/// Capabilities required to use 'vertex/fragment/geometry shader only' texture gather operations
+/// [Compound]
 alias texture_gather = texture_sm_4_1_vertex_fragment_geometry | GL_ARB_texture_gather;
+/// Capabilities required to query image (RWTexture) sample info
+/// [Compound]
 alias image_samples = texture_sm_4_1_compute_fragment | GL_ARB_shader_texture_image_samples;
+/// Capabilities required to query image (RWTexture) size info
+/// [Compound]
 alias image_size = texture_sm_4_1_compute_fragment | GL_ARB_shader_image_size;
+/// Capabilities required to query texture sample info
+/// [Compound]
 alias texture_size = texture_sm_4_1 | GL_ARB_shader_image_size;
+/// Capabilities required to query texture LOD info
+/// [Compound]
 alias texture_querylod = texture_sm_4_1 | GL_EXT_texture_query_lod;
+/// Capabilities required to query texture level info
+/// [Compound]
 alias texture_querylevels = texture_sm_4_1 | GL_ARB_texture_query_levels;
+/// Capabilities required to query shadow texture lod info
+/// [Compound]
 alias texture_shadowlod = texture_sm_4_1 | GL_EXT_texture_shadow_lod
                         | texture_sm_4_1;
 
+/// (GLSL/SPIRV) Capabilities required to use GLSL-tier-1 float-atomic operations
+/// [Compound]
 alias atomic_glsl_float1 = GL_EXT_shader_atomic_float;
+/// (GLSL/SPIRV) Capabilities required to use GLSL-tier-2 float-atomic operations
+/// [Compound]
 alias atomic_glsl_float2 = GL_EXT_shader_atomic_float2;
+/// (GLSL/SPIRV) Capabilities required to use NVAPI GLSL-fp16 float-atomic operations
+/// [Compound]
 alias atomic_glsl_halfvec = GL_NV_shader_atomic_fp16_vector;
+/// (GLSL/SPIRV) Capabilities required to use GLSL-400 atomic operations
+/// [Compound]
 alias atomic_glsl = spirv_1_0 | _GLSL_400;
+/// (GLSL/SPIRV) Capabilities required to use int64/uint64 atomic operations
+/// [Compound]
 alias atomic_glsl_int64 = atomic_glsl + GL_EXT_shader_atomic_int64;
+/// User should not use this capability
+/// [Other]
 alias GLSL_430_SPIRV_1_0_compute = GLSL_430_SPIRV_1_0 + compute;
+/// (GLSL/SPIRV) Capabilities required to use image load/image store operations
+/// [Compound]
 alias image_loadstore = GL_EXT_shader_image_load_store + GLSL_420;
+/// Capabilities required to use NonUniform qualifier
+/// [Compound]
 alias nonuniformqualifier = sm_5_1;
+/// Capabilities required to use 'printf'
+/// [Compound]
 alias printf = GL_EXT_debug_printf | _sm_4_0 | _cuda_sm_2_0 | cpp;
+/// Capabilities required to use basic TextureFootprint operations
+/// [Compound]
 alias texturefootprint = GL_NV_shader_texture_footprint + GLSL_450 | hlsl_nvapi + _sm_4_0;
+/// Capabilities required to use TextureFootprint clamp operations
+/// [Compound]
 alias texturefootprintclamp = texturefootprint + GL_ARB_sparse_texture_clamp;
 
+/// Capabilities required to use sm_4_0 features apart of GL_ARB_gpu_shader5 
+/// [Compound]
 alias shader5_sm_4_0 = GL_ARB_gpu_shader5 | sm_4_0_version;
+/// Capabilities required to use sm_5_0 features apart of GL_ARB_gpu_shader5 
+/// [Compound]
 alias shader5_sm_5_0 = GL_ARB_gpu_shader5 | sm_5_0_version;
 
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_basic'
+/// [Compound]
 alias subgroup_basic = GL_KHR_shader_subgroup_basic | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_ballot'
+/// [Compound]
 alias subgroup_ballot = spirv_1_0 + GL_KHR_shader_subgroup_ballot
                       | glsl + GL_KHR_shader_subgroup_ballot + shader5_sm_5_0 
                       | _sm_6_0  + shader5_sm_5_0 
                       | _cuda_sm_7_0 + shader5_sm_5_0
                       ;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_ballot_activemask'
+/// [Compound]
 alias subgroup_ballot_activemask = spirv_1_0 + GL_KHR_shader_subgroup_ballot
                       | glsl + GL_KHR_shader_subgroup_ballot 
                       | _sm_6_0
                       | _cuda_sm_7_0
                       ;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_basic_ballot'
+/// [Compound]
 alias subgroup_basic_ballot = glsl + GL_KHR_shader_subgroup_basic + subgroup_ballot 
                             | spirv + GL_KHR_shader_subgroup_basic + subgroup_ballot
                             | hlsl + subgroup_ballot
                             | cuda + subgroup_ballot
                             ;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_vote'
+/// [Compound]
 alias subgroup_vote = GL_KHR_shader_subgroup_vote | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_vote'
+/// [Compound]
 alias shaderinvocationgroup = subgroup_vote;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_arithmetic'
+/// [Compound]
 alias subgroup_arithmetic = GL_KHR_shader_subgroup_arithmetic | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_shuffle'
+/// [Compound]
 alias subgroup_shuffle = GL_KHR_shader_subgroup_shuffle | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_shufle_relative'
+/// [Compound]
 alias subgroup_shufflerelative = GL_KHR_shader_subgroup_shuffle_relative | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_clustered'
+/// [Compound]
 alias subgroup_clustered = GL_KHR_shader_subgroup_clustered | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_quad'
+/// [Compound]
 alias subgroup_quad = GL_KHR_shader_subgroup_quad | _sm_6_0 | _cuda_sm_7_0;
+/// Capabilities required to use GLSL-style subgroup operations 'subgroup_partitioned'
+/// [Compound]
 alias subgroup_partitioned = GL_NV_shader_subgroup_partitioned + subgroup_ballot_activemask | _sm_6_5 | _cuda_sm_7_0;
 
+/// (All implemented targets) Capabilities required to use atomic operations of GLSL tier-1 float atomics
+/// [Compound]
 alias atomic_glsl_hlsl_nvapi_cuda_metal_float1 = atomic_glsl_float1 | hlsl_nvapi + _sm_4_0 | _cuda_sm_2_0 | metal;
+/// (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_5 tier atomics)
+/// [Compound]
 alias atomic_glsl_hlsl_nvapi_cuda5_int64 = atomic_glsl_int64 | hlsl_nvapi + _sm_4_0 | _cuda_sm_6_0;
+/// (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_6 tier atomics)
+/// [Compound]
 alias atomic_glsl_hlsl_nvapi_cuda6_int64 = atomic_glsl_int64 | hlsl_nvapi + _sm_4_0 | _cuda_sm_6_0;
+/// (All implemented targets) Capabilities required to use atomic operations of int64 (cuda_sm_9 tier atomics)
+/// [Compound]
 alias atomic_glsl_hlsl_nvapi_cuda9_int64 = atomic_glsl_int64 | hlsl_nvapi + _sm_4_0 | _cuda_sm_9_0;
 
+/// (All implemented targets) Capabilities required to use atomic operations
+/// [Compound]
 alias atomic_glsl_hlsl_cuda_metal = atomic_glsl | _sm_5_0 | _cuda_sm_2_0 | metal;
+/// (All implemented targets) Capabilities required to use atomic operations (cuda_sm_9 tier atomics)
+/// [Compound]
 alias atomic_glsl_hlsl_cuda9_int64 = atomic_glsl_int64 | _sm_6_6 | _cuda_sm_9_0 | metal;
 
+/// Capabilities required to enable helper-lane demotion
+/// [Compound]
 alias helper_lane = _sm_6_0 + fragment
                    | GL_EXT_demote_to_helper_invocation + fragment
                    | metal + fragment
                    ;
 
+/// Capabilities required to enable shader breakpoints
+/// [Compound]
 alias breakpoint = GL_EXT_debug_printf | hlsl | _cuda_sm_8_0 | cpp;
 
+/// Collection of capabilities for raytracing with all raytracing stages.
+/// [Compound]
 alias raytracing_allstages = raytracing_stages + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stage of anyhit.
+/// [Compound]
 alias raytracing_anyhit = anyhit + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stage of intersection.
+/// [Compound]
 alias raytracing_intersection = intersection + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stages of anyhit and closesthit.
+/// [Compound]
 alias raytracing_anyhit_closesthit = anyhit_closesthit + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stages of anyhit, closesthit, and intersection.
+/// [Compound]
 alias raytracing_anyhit_closesthit_intersection = anyhit_closesthit_intersection + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stages of raygen, closesthit, and miss.
+/// [Compound]
 alias raytracing_raygen_closesthit_miss = raygen_closesthit_miss + raytracing;
+
+/// Collection of capabilities for raytracing with the shader stages of anyhit, closesthit, intersection, and miss.
+/// [Compound]
 alias raytracing_anyhit_closesthit_intersection_miss = anyhit_closesthit_intersection_miss + raytracing;
+
+/// Collection of capabilities for raytracing the shader stages of raygen, closesthit, miss, and callable.
+/// [Compound]
 alias raytracing_raygen_closesthit_miss_callable = raygen_closesthit_miss_callable + raytracing;
+
+/// Collection of capabilities for raytracing + ray_tracing_position_fetch and the shader stages of anyhit and closesthit.
+/// [Compound]
 alias raytracing_position = raytracing + GL_EXT_ray_tracing_position_fetch_ray_tracing + anyhit_closesthit;
+
+/// Collection of capabilities for raytracing + motion blur and the shader stages of anyhit, closesthit, intersection, and miss.
+/// [Compound]
 alias raytracing_motionblur_anyhit_closesthit_intersection_miss = anyhit_closesthit_intersection_miss + raytracing_motionblur;
+
+/// Collection of capabilities for raytracing + motion blur and the shader stages of raygen, closesthit, and miss.
+/// [Compound]
 alias raytracing_motionblur_raygen_closesthit_miss = raygen_closesthit_miss + raytracing_motionblur;
+
+/// Collection of capabilities for rayquery + ray_tracing_position_fetch.
+/// [Compound]
 alias rayquery_position = rayquery + GL_EXT_ray_tracing_position_fetch_ray_query;
+
+/// Collection of capabilities for raytracing + shader execution reordering and the shader stage of raygen.
+/// [Compound]
 alias ser_raygen = raygen + ser;
+
+/// Collection of capabilities for raytracing + shader execution reordering and the shader stages of raygen, closesthit, and miss.
+/// [Compound]
 alias ser_raygen_closesthit_miss = raygen_closesthit_miss + ser;
+
+/// Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit, closesthit, intersection, and miss.
+/// [Compound]
 alias ser_any_closesthit_intersection_miss = anyhit_closesthit_intersection_miss + ser;
+
+/// Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit, closesthit, and intersection.
+/// [Compound]
 alias ser_anyhit_closesthit_intersection = anyhit_closesthit_intersection + ser;
+
+/// Collection of capabilities for raytracing + shader execution reordering and the shader stages of anyhit and closesthit.
+/// [Compound]
 alias ser_anyhit_closesthit = anyhit_closesthit + ser;
+
+/// Collection of capabilities for raytracing + motion blur + shader execution reordering and the shader stages of raygen, closesthit, and miss.
+/// [Compound]
 alias ser_motion_raygen_closesthit_miss = raygen_closesthit_miss + ser_motion;
+
+/// Collection of capabilities for raytracing raytracing + motion blur + shader execution reordering and the shader stage of raygen.
+/// [Compound]
 alias ser_motion_raygen = raygen + ser_motion;
 
+/// User should not use this capability
+/// [Other]
 alias all = _sm_6_7 + hlsl_nvapi
           | sm_6_7
              + ser + shaderclock + texturefootprint + fragmentshaderinterlock + _GL_NV_shader_subgroup_partitioned
diff --git a/tools/slang-capability-generator/capability-generator-main.cpp b/tools/slang-capability-generator/capability-generator-main.cpp
index 711532273..674aca7fd 100644
--- a/tools/slang-capability-generator/capability-generator-main.cpp
+++ b/tools/slang-capability-generator/capability-generator-main.cpp
@@ -65,6 +65,95 @@ static void _removeFromOtherAtomsNotInThis(HashSet<const CapabilityDef*> thisSet
         otherSet.remove(atomToRemove);
 }
 
+enum class AutoDocHeaderGroup : UInt
+{
+    Targets = 0,
+    Stages,
+    Versions,
+    Extensions,
+    Compound,
+    Other,
+    Count,
+    Invalid,
+};
+
+UnownedStringSlice getHeaderNameFromAutoDocHeaderGroup(UInt headerGroup)
+{
+    switch (headerGroup)
+    {
+    case (UInt)AutoDocHeaderGroup::Targets:
+        return UnownedStringSlice("Targets");
+    case (UInt)AutoDocHeaderGroup::Stages:
+        return UnownedStringSlice("Stages");
+    case (UInt)AutoDocHeaderGroup::Extensions:
+        return UnownedStringSlice("Extensions");
+    case (UInt)AutoDocHeaderGroup::Versions:
+        return UnownedStringSlice("Versions");
+    case (UInt)AutoDocHeaderGroup::Compound:
+        return UnownedStringSlice("Compound Capabilities");
+    case (UInt)AutoDocHeaderGroup::Other:
+        return UnownedStringSlice("Other");
+    default:
+        SLANG_ASSERT("Unknown `AutoDocHeaderGroup`");
+        return UnownedStringSlice("");
+    }
+}
+
+UnownedStringSlice getHeaderDescriptionFromAutoDocHeaderGroup(UInt headerGroup)
+{
+    switch (headerGroup)
+    {
+    case (UInt)AutoDocHeaderGroup::Targets:
+        return UnownedStringSlice("Capabilities to specify code generation targets (`glsl`, `spirv`...)");
+    case (UInt)AutoDocHeaderGroup::Stages:
+        return UnownedStringSlice("Capabilities to specify code generation stages (`vertex`, `fragment`...)");
+    case (UInt)AutoDocHeaderGroup::Extensions:
+        return UnownedStringSlice("Capabilities to specify extensions (`GL_EXT`, `SPV_EXT`...)");
+    case (UInt)AutoDocHeaderGroup::Versions:
+        return UnownedStringSlice("Capabilities to specify versions of a code generation target (`sm_5_0`, `GLSL_400`...)");
+    case (UInt)AutoDocHeaderGroup::Compound:
+        return UnownedStringSlice("Capabilities to specify capabilities created by other capabilities (`raytracing`, `meshshading`...)");
+    case (UInt)AutoDocHeaderGroup::Other:
+        return UnownedStringSlice("Capabilities which may be deprecated");
+    default:
+        SLANG_ASSERT("Unknown `AutoDocHeaderGroup`");
+        return UnownedStringSlice("");
+    }
+}
+
+AutoDocHeaderGroup getAutoDocHeaderGroupFromTag(DiagnosticSink* sink, UnownedStringSlice headerGroupName, SourceLoc loc)
+{
+    if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("Other")))
+        return AutoDocHeaderGroup::Other;
+    else if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("Target")))
+        return AutoDocHeaderGroup::Targets;
+    else if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("Stage")))
+        return AutoDocHeaderGroup::Stages;
+    else if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("EXT")))
+        return AutoDocHeaderGroup::Extensions;
+    else if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("Version")))
+        return AutoDocHeaderGroup::Versions;
+    else if (headerGroupName.caseInsensitiveEquals(UnownedStringSlice("Compound")))
+        return AutoDocHeaderGroup::Compound;
+    else
+    {
+        sink->diagnose(loc, Diagnostics::invalidDocCommentHeader, headerGroupName);
+        return AutoDocHeaderGroup::Invalid;
+    }
+}
+
+struct AutoDocInfo
+{
+    String comment;
+    AutoDocHeaderGroup headerGroup;
+
+    AutoDocInfo()
+    {
+        comment = {};
+        headerGroup = AutoDocHeaderGroup::Other;
+    }
+};
+
 struct CapabilityDef : public RefObject
 {
 public:
@@ -80,6 +169,7 @@ public:
         this->sourceLoc = other.sourceLoc;
         this->keyAtomsPresent = other.keyAtomsPresent;
         this->sharedContext = other.sharedContext;
+        this->docComment = other.docComment;
     }
 
     String name;
@@ -91,6 +181,7 @@ public:
     List<List<CapabilityDef*>> canonicalRepresentation;
     SerializedArrayView serializedCanonicalRepresentation;
     SourceLoc sourceLoc;
+    AutoDocInfo docComment;
     /// Stores key atoms a CapabilityDef refers to. 
     /// Shared key atoms: key atoms shared between every individual set in a canonicalRepresentation, added together.
     HashSet<const CapabilityDef*> keyAtomsPresent;
@@ -174,6 +265,24 @@ public:
     }
 };
 
+/// Advances through BlockComment/LineComment, otherwise, "advanceIf 'type' is the next token"
+enum class AdvanceOptions : UInt
+{
+    None = 0 << 0,
+    SkipComments = 1 << 0,
+};
+
+template<AdvanceOptions L, AdvanceOptions R>
+constexpr bool ContainsOption()
+{
+    return (UInt)L & (UInt)R;
+}
+
+static bool isInternalDef(RefPtr<CapabilityDef> def)
+{
+    return def->name.startsWith("_");
+}
+
 struct CapabilityDefParser
 {
     CapabilityDefParser(
@@ -195,9 +304,19 @@ struct CapabilityDefParser
 
     TokenReader m_tokenReader;
 
+    template<AdvanceOptions advanceOptions>
     bool advanceIf(TokenType type)
     {
-        if (m_tokenReader.peekTokenType() == type)
+        auto peekToken = m_tokenReader.peekTokenType();
+        if constexpr (ContainsOption<advanceOptions, AdvanceOptions::SkipComments>())
+        {
+            while (peekToken == TokenType::BlockComment || peekToken == TokenType::LineComment)
+            {
+                m_tokenReader.advanceToken();
+                peekToken = m_tokenReader.peekTokenType();
+            }
+        }
+        if (peekToken == type)
         {
             m_tokenReader.advanceToken();
             return true;
@@ -205,9 +324,15 @@ struct CapabilityDefParser
         return false;
     }
 
+    template<AdvanceOptions advanceOptions>
     SlangResult readToken(TokenType type, Token& nextToken)
     {
         nextToken = m_tokenReader.advanceToken();
+        if constexpr (ContainsOption<advanceOptions, AdvanceOptions::SkipComments>())
+        {
+            while (nextToken.type == TokenType::BlockComment || nextToken.type == TokenType::LineComment)
+                nextToken = m_tokenReader.advanceToken();
+        }
         if (nextToken.type != type)
         {
             m_sink->diagnose(nextToken.loc, Diagnostics::unexpectedTokenExpectedTokenType, nextToken, type);
@@ -216,10 +341,11 @@ struct CapabilityDefParser
         return SLANG_OK;
     }
 
+    template<AdvanceOptions advanceOptions>
     SlangResult readToken(TokenType type)
     {
         Token nextToken;
-        return readToken(type, nextToken);
+        return readToken<advanceOptions>(type, nextToken);
     }
 
     SlangResult parseConjunction(CapabilityConjunctionExpr& expr)
@@ -227,7 +353,7 @@ struct CapabilityDefParser
         for (;;)
         {
             Token nameToken;
-            SLANG_RETURN_ON_FAIL(readToken(TokenType::Identifier, nameToken));
+            SLANG_RETURN_ON_FAIL(readToken<AdvanceOptions::SkipComments>(TokenType::Identifier, nameToken));
             CapabilityDef* def = nullptr;
             if (m_mapNameToCapability.tryGetValue(nameToken.getContent(), def))
             {
@@ -238,7 +364,7 @@ struct CapabilityDefParser
                 m_sink->diagnose(nameToken.loc, Diagnostics::undefinedIdentifier, nameToken);
                 return SLANG_FAIL;
             }
-            if (!(advanceIf(TokenType::OpAdd)))
+            if (!(advanceIf<AdvanceOptions::SkipComments>(TokenType::OpAdd)))
                 break;
         }
         return SLANG_OK;
@@ -252,7 +378,7 @@ struct CapabilityDefParser
             conjunction.sourceLoc = this->m_tokenReader.m_cursor->getLoc();
             SLANG_RETURN_ON_FAIL(parseConjunction(conjunction));
             expr.conjunctions.add(conjunction);
-            if (!advanceIf(TokenType::OpBitOr))
+            if (!advanceIf<AdvanceOptions::SkipComments>(TokenType::OpBitOr))
                 break;
         }
         return SLANG_OK;
@@ -277,7 +403,7 @@ struct CapabilityDefParser
             // Try to pack `_atom` and `atom` into the same per key List
             String name = i->name;
             if(i->name.startsWith("_"))
-                name = name.subString(1, name.getLength()-1);
+                name = name.subString(1, name.getLength() - 1);
             nameToInternalAndExternalAtom[name].add(i);
         }
         for(auto i : nameToInternalAndExternalAtom)
@@ -291,16 +417,29 @@ struct CapabilityDefParser
             }
         }
     }
+
+    bool isLineSuccessive(HumaneSourceLoc above, HumaneSourceLoc below)
+    {
+        return above.line + 1 == below.line;
+    }
+
     SlangResult parseDefs()
     {
-        auto tokens = m_lexer->lexAllSemanticTokens();
+        auto tokens = m_lexer->lexAllMarkupTokens();
         m_tokenReader = TokenReader(tokens);
+        AutoDocInfo successiveComments = AutoDocInfo();
+        HumaneSourceLoc successiveCommentLine = {};
+
         for (;;)
         {
+            auto nextToken = m_tokenReader.advanceToken();
+
+            if (!isLineSuccessive(successiveCommentLine, m_lexer->m_sourceView->getHumaneLoc(nextToken.getLoc())))
+                successiveComments = AutoDocInfo();
+
             RefPtr<CapabilityDef> def = new CapabilityDef();
             def->sharedContext = &m_sharedContext;
             def->flavor = CapabilityFlavor::Normal;
-            auto nextToken = m_tokenReader.advanceToken();
             if (nextToken.getContent() == "alias")
             {
                 def->flavor = CapabilityFlavor::Alias;
@@ -313,6 +452,51 @@ struct CapabilityDefParser
             {
                 def->flavor = CapabilityFlavor::Normal;
             }
+            else if (nextToken.type == TokenType::BlockComment)
+            {
+                // Do not auto-document
+                continue;
+            }
+            else if (nextToken.type == TokenType::LineComment)
+            {
+                // Auto-document if the preceeding token to an identifier is '///'
+                // complete rules described in `source\slang\slang-capabilities.capdef`
+                auto commentContent = nextToken.getContent();
+                
+                // remove "//"
+                commentContent = commentContent.subString(2, commentContent.getLength() - 2);
+                if (commentContent.startsWith("/"))
+                {
+                    auto commentLine = m_lexer->m_sourceView->getHumaneLoc(nextToken.getLoc());      
+
+                    // Reset the `successiveCommentLine` to our newest commentLine
+                    successiveCommentLine = commentLine;
+
+                    // remove "/" from "///"
+                    commentContent = commentContent.subString(1, commentContent.getLength() - 1).trim();
+                    
+                    // Check if we have a `[header]`
+                    if (commentContent.startsWith("["))
+                    {
+                        // Make a substring of `header]`
+                        auto consumedLeftBracketOfHeader = commentContent.subString(1, commentContent.getLength() - 1);
+                        // Find a `]` of `header]` if it exists
+                        auto indexOfHeaderEnd = consumedLeftBracketOfHeader.indexOf(']');
+                        if (indexOfHeaderEnd != -1)
+                        {
+                            // We found our `header`
+                            auto headerName = consumedLeftBracketOfHeader.subString(0, indexOfHeaderEnd);
+                            successiveComments.headerGroup = getAutoDocHeaderGroupFromTag(m_sink, headerName, nextToken.getLoc());
+                            continue;
+                        }
+                        // If we did not find a header this is a regular comment
+                    }
+                    successiveComments.comment.append("> ");
+                    successiveComments.comment.append(commentContent);
+                    successiveComments.comment.append("\n");
+                }
+                continue;
+            }
             else if (nextToken.type == TokenType::EndOfFile)
             {
                 break;
@@ -324,35 +508,41 @@ struct CapabilityDefParser
             }
 
             Token nameToken;
-            SLANG_RETURN_ON_FAIL(readToken(TokenType::Identifier, nameToken));
+            SLANG_RETURN_ON_FAIL(readToken<AdvanceOptions::SkipComments>(TokenType::Identifier, nameToken));
             def->name = nameToken.getContent();
 
             if (def->flavor == CapabilityFlavor::Normal)
             {
-                if (advanceIf(TokenType::Colon))
+                if (advanceIf<AdvanceOptions::SkipComments>(TokenType::Colon))
                 {
                     SLANG_RETURN_ON_FAIL(parseExpr(def->expr));
                 }
-                if (advanceIf(TokenType::OpAssign))
+                if (advanceIf<AdvanceOptions::SkipComments>(TokenType::OpAssign))
                 {
                     Token rankToken;
-                    SLANG_RETURN_ON_FAIL(readToken(TokenType::IntegerLiteral, rankToken));
+                    SLANG_RETURN_ON_FAIL(readToken<AdvanceOptions::SkipComments>(TokenType::IntegerLiteral, rankToken));
                     def->rank = stringToInt(rankToken.getContent());
                 }
+                def->docComment = successiveComments;
+                if(def->docComment.comment.getLength() == 0 && !isInternalDef(def))
+                    m_sink->diagnose(nextToken.loc, Diagnostics::requiresDocComment, def->name);
             }
             else if (def->flavor == CapabilityFlavor::Alias)
             {
-                SLANG_RETURN_ON_FAIL(readToken(TokenType::OpAssign));
+                SLANG_RETURN_ON_FAIL(readToken<AdvanceOptions::SkipComments>(TokenType::OpAssign));
                 SLANG_RETURN_ON_FAIL(parseExpr(def->expr));
+                def->docComment = successiveComments;
+                if (def->docComment.comment.getLength() == 0 && !isInternalDef(def))
+                    m_sink->diagnose(nextToken.loc, Diagnostics::requiresDocComment, def->name);
             }
             else if (def->flavor == CapabilityFlavor::Abstract)
             {
-                if (advanceIf(TokenType::Colon))
+                if (advanceIf<AdvanceOptions::SkipComments>(TokenType::Colon))
                 {
                     SLANG_RETURN_ON_FAIL(parseExpr(def->expr));
                 }
             }
-            SLANG_RETURN_ON_FAIL(readToken(TokenType::Semicolon));
+            SLANG_RETURN_ON_FAIL(readToken<AdvanceOptions::SkipComments>(TokenType::Semicolon));
             m_defs.add(def);
             if (!m_mapNameToCapability.addIfNotExists(def->name, m_defs.getLast()))
             {
@@ -723,6 +913,84 @@ UIntSet atomSetToUIntSet(const List<CapabilityDef*>& atomSet)
     return set;
 }
 
+void printDocForCapabilityDef(StringBuilder& sbDoc, RefPtr<CapabilityDef> def, List<StringBuilder>& sbDocSections)
+{
+    if (isInternalDef(def)
+        || def->flavor == CapabilityFlavor::Abstract
+        || def->docComment.headerGroup == AutoDocHeaderGroup::Invalid)
+        return;
+
+    auto& sbDocSection = sbDocSections[(UInt)def->docComment.headerGroup];
+    sbDocSection << "\n" << "`" << def->name << "`\n";
+    sbDocSection << def->docComment.comment;
+}
+
+List<StringBuilder> setupDocCommentHeaderStringBuilders()
+{
+    List<StringBuilder> sbDocSections;
+    sbDocSections.setCount((UInt)AutoDocHeaderGroup::Count);
+    for (UInt i = 0; i < (UInt)AutoDocHeaderGroup::Count; i++)
+    {
+        sbDocSections[i] << "\n" << getHeaderNameFromAutoDocHeaderGroup(i) << "\n----------------------\n";
+        sbDocSections[i] << "*" << getHeaderDescriptionFromAutoDocHeaderGroup(i) << "*\n";
+    }
+    return sbDocSections;
+}
+
+/// "[Link Name](fileName#Link-Name)"
+void addHyperLink(StringBuilder& sbDoc, UnownedStringSlice suffix)
+{
+    String suffixReformatted = "";
+
+    for (auto i : suffix)
+    {
+        if (i == ' ')
+        {
+            suffixReformatted.appendChar('-');
+            continue;
+        }
+        suffixReformatted.appendChar(i);
+    }
+    sbDoc << "[" << suffix << "](#" << suffixReformatted << ")";
+}
+
+void setupDocumentationHeader(StringBuilder& sbDoc, const String& outPath)
+{
+    sbDoc << R"(
+---
+layout: user-guide
+---
+
+Capability Atoms
+============================
+
+### Sections:
+
+)";
+
+    // Hyper-Links
+    for (UInt i = 0; i < (UInt)AutoDocHeaderGroup::Count; i++)
+    {
+        auto headerName = getHeaderNameFromAutoDocHeaderGroup(i);
+        sbDoc << i + 1 << ". "; // "i. " 
+        addHyperLink(sbDoc, headerName);
+        sbDoc << "\n";
+    }
+}
+
+SlangResult generateDocumentation(DiagnosticSink* sink, List<RefPtr<CapabilityDef>>& defs, StringBuilder& sbDoc, const String& outPath)
+{
+    setupDocumentationHeader(sbDoc, outPath);
+
+    List<StringBuilder> sbDocSections = setupDocCommentHeaderStringBuilders();
+    for (auto def : defs)
+    {
+        printDocForCapabilityDef(sbDoc, def, sbDocSections);
+    }
+    for (auto stringBuilder : sbDocSections)
+        sbDoc << stringBuilder.toString();
+    return 1;
+}
 SlangResult generateDefinitions(DiagnosticSink* sink, List<RefPtr<CapabilityDef>>& defs, StringBuilder& sbHeader, StringBuilder& sbCpp)
 {
    
@@ -934,14 +1202,14 @@ SlangResult generateDefinitions(DiagnosticSink* sink, List<RefPtr<CapabilityDef>
     
     sbCpp << "};\n";
 
-    sbCpp
-        << "void freeCapabilityDefs()\n"
-        << "{\n"
-        << "    for (auto& cap : kCapabilityArray) { cap = CapabilityAtomSet(); }\n"
-        << "    kAnyTargetUIntSetBuffer = CapabilityAtomSet();\n"
-        << "    kAnyStageUIntSetBuffer = CapabilityAtomSet();\n"
-        << "}\n";
-    return SLANG_OK;
+sbCpp
+<< "void freeCapabilityDefs()\n"
+<< "{\n"
+<< "    for (auto& cap : kCapabilityArray) { cap = CapabilityAtomSet(); }\n"
+<< "    kAnyTargetUIntSetBuffer = CapabilityAtomSet();\n"
+<< "    kAnyStageUIntSetBuffer = CapabilityAtomSet();\n"
+<< "}\n";
+return SLANG_OK;
 }
 
 
@@ -959,7 +1227,7 @@ SlangResult parseDefFile(DiagnosticSink* sink, String inputPath, List<RefPtr<Cap
     RootNamePool rootPool;
     namePool.setRootNamePool(&rootPool);
     lexer.initialize(sourceView, sink, &namePool, sourceManager->getMemoryArena());
-   
+
     CapabilityDefParser parser(&lexer, sink, capabilitySharedContext);
 
     SLANG_RETURN_ON_FAIL(parser.parseDefs());
@@ -1031,8 +1299,22 @@ int main(int argc, const char* const* argv)
         return 1;
     }
 
+    auto outDocPath = Path::combine(targetDir, "../../docs/user-guide/a3-02-reference-capability-atoms.md");
+    if (!File::exists(outDocPath))
+    {
+        sink.diagnose(SourceLoc(), Diagnostics::couldNotFindValidDocumentationOutputPath, outDocPath);
+    }
+
+    StringBuilder sbDoc;
+    if (SLANG_FAILED(generateDocumentation(&sink, defs, sbDoc, outDocPath)))
+    {
+        printDiagnostics(&sink);
+        return 1;
+    }
+
     writeIfChanged(outHeaderPath, sbHeader.produceString());
     writeIfChanged(outCppPath, sbCpp.produceString());
+    writeIfChanged(outDocPath, sbDoc.produceString());
 
     List<String> opnames;
     for (auto def : defs)
diff --git a/tools/slang-capability-generator/slang-capability-diagnostic-defs.h b/tools/slang-capability-generator/slang-capability-diagnostic-defs.h
index b6c4425a2..7f80bda6a 100644
--- a/tools/slang-capability-generator/slang-capability-diagnostic-defs.h
+++ b/tools/slang-capability-generator/slang-capability-diagnostic-defs.h
@@ -33,6 +33,7 @@ DIAGNOSTIC(    2, Error, cannotFindFile, "cannot find file '$0'.")
 DIAGNOSTIC(    4, Error, cannotWriteOutputFile, "cannot write output file '$0'.")
 DIAGNOSTIC(    5, Error, failedToLoadDynamicLibrary, "failed to load dynamic library '$0'")
 DIAGNOSTIC(    6, Error, tooManyOutputPathsSpecified, "$0 output paths specified, but only $1 entry points given")
+DIAGNOSTIC(    7, Warning, couldNotFindValidDocumentationOutputPath, "could not find valid documentation output path at $0")
 
 //
 // 2xxxx - Parsing
@@ -41,6 +42,8 @@ DIAGNOSTIC(    6, Error, tooManyOutputPathsSpecified, "$0 output paths specified
 DIAGNOSTIC(20003, Error, unexpectedToken, "unexpected $0")
 DIAGNOSTIC(20001, Error, unexpectedTokenExpectedTokenType, "unexpected $0, expected $1")
 DIAGNOSTIC(20001, Error, unexpectedTokenExpectedTokenName, "unexpected $0, expected '$1'")
+DIAGNOSTIC(20004, Warning, requiresDocComment, "'$0' requires a documentation comment \"///\"")
+DIAGNOSTIC(20004, Warning, invalidDocCommentHeader, "got documentation comment '[$0]', expected one of: [Target] [Stage] [EXT] [Version] [Compound] [Other]")
 
 DIAGNOSTIC(0, Error, tokenNameExpectedButEOF, "\"$0\" expected but end of file encountered.")
 DIAGNOSTIC(0, Error, tokenTypeExpectedButEOF, "$0 expected but end of file encountered.")