From 4e62f98f3abfa1b1e125c371160ed309ca5b6c04 Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Tue, 14 Jan 2025 10:38:46 -0800
Subject: Fix documentation on DescriptorHandle. (#6062)

* Fix documentation on DescriptorHandle.

* Fix.

* format code

---------

Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
---
 cmake/SlangTarget.cmake      | 12 ++++++++----
 source/slang/hlsl.meta.slang | 16 +++++++++++++++-
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/cmake/SlangTarget.cmake b/cmake/SlangTarget.cmake
index 45e7cf1e1..eae5cf35e 100644
--- a/cmake/SlangTarget.cmake
+++ b/cmake/SlangTarget.cmake
@@ -505,10 +505,14 @@ function(slang_add_target dir type)
         endif()
         install(
             TARGETS ${target} ${export_args}
-            ARCHIVE DESTINATION ${archive_subdir} ${ARGN}
-            LIBRARY DESTINATION ${library_subdir} ${ARGN}
-            RUNTIME DESTINATION ${runtime_subdir} ${ARGN}
-            PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ${ARGN}
+            ARCHIVE DESTINATION ${archive_subdir}
+            ${ARGN}
+            LIBRARY DESTINATION ${library_subdir}
+            ${ARGN}
+            RUNTIME DESTINATION ${runtime_subdir}
+            ${ARGN}
+            PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+            ${ARGN}
         )
     endmacro()
 
diff --git a/source/slang/hlsl.meta.slang b/source/slang/hlsl.meta.slang
index 7964e26d8..11c4ab6f4 100644
--- a/source/slang/hlsl.meta.slang
+++ b/source/slang/hlsl.meta.slang
@@ -20932,6 +20932,8 @@ struct ConstBufferPointer
 // new aliased bindings for each distinct cast type.
 //
 
+//@public:
+
 /// Represent the kind of a descriptor type.
 enum DescriptorKind
 {
@@ -21048,8 +21050,18 @@ ${{{{
 }
 }}}}
 
-/// Represents a bindless resource handle. A bindless resource handle is always a concrete type and can be
+/// Represents a bindless handle to a descriptor. A descriptor handle is always an ordinary data type and can be
 /// declared in any memory location.
+/// @remarks Opaque descriptor types such as textures(`Texture2D` etc.), `SamplerState` and buffers (e.g. `StructuredBuffer`)
+/// can have undefined size and data representation on many targets. On platforms such as Vulkan and D3D12, descriptors are
+/// communicated to the shader code by calling the host side API to write the descriptor into a descriptor set or table, instead
+/// of directly writing bytes into an ordinary GPU accessible buffer. As a result, oapque handle types cannot be used in places
+/// that refer to a ordinary buffer location, such as as element types of a `StructuredBuffer`.
+/// However, a `DescriptorHandle<T>` stores a handle (or address) to the actual descriptor, and is always an ordinary data type
+/// that can be manipulated directly in the shader code. This gives the developer the flexibility to embed and pass around descriptor
+/// parameters throughout the code, to enable cleaner modular designs.
+/// See [User Guide](https://shader-slang.com/slang/user-guide/convenience-features.html#descriptorhandle-for-bindless-descriptor-access)
+/// for more information on how to use `DescriptorHandle<T>` in your code.
 __magic_type(DescriptorHandleType)
 __intrinsic_type($(kIROp_DescriptorHandleType))
 struct DescriptorHandle<T:IOpaqueDescriptor> : IComparable
@@ -21140,6 +21152,8 @@ extern T getDescriptorFromHandle<T:IOpaqueDescriptor>(DescriptorHandle<T> handle
 __intrinsic_op($(kIROp_NonUniformResourceIndex))
 DescriptorHandle<T> nonuniform<T:IOpaqueDescriptor>(DescriptorHandle<T> ptr);
 
+//@hidden:
+
 __glsl_version(450)
 __glsl_extension(GL_ARB_shader_clock)
 [require(glsl_spirv, GL_ARB_shader_clock)]
-- 
cgit v1.2.3