Document notable `__ref` uss in stdlib. Remove user docs use of '__ref'. (#4799)

1. Document `__ref` in stdlib.
2. Remove `__ref` example in `docs\user-guide\a1-04-interop.md`
3. New example in `docs\user-guide\a1-04-interop.md` to compensate for no longer providing an example that uses `&` and `OpCapability`/`OpExtension`.

Co-authored-by: Yong He <yonghe@outlook.com>

3 files changed, 44 insertions, 9 deletions

diff --git a/docs/user-guide/a1-04-interop.md b/docs/user-guide/a1-04-interop.md
index b7715779f..a13f75c48 100644
--- a/docs/user-guide/a1-04-interop.md
+++ b/docs/user-guide/a1-04-interop.md
@@ -169,19 +169,39 @@ When used as part of an expression, the Slang type of the `spirv_asm` construct
 result: <type> = ...
 ```
 
-You can use the `$` prefix to begin an anti-quote of a Slang expression inside a `spirv_asm` block. This is commonly used to refer to a Slang variable, such as `localVar` in the example, as an operand. Additionally, the `$$` prefix is used to reference a Slang type, such as the `$$uint` references in the example. You can also use the `&` prefix to refer to an l-value as a pointer-typed value in SPIRV.
+You can use the `$` prefix to begin an anti-quote of a Slang expression inside a `spirv_asm` block. This is commonly used to refer to a Slang variable, such as `localVar` in the example, as an operand. Additionally, the `$$` prefix is used to reference a Slang type, such as the `$$uint` references in the example. 
 
-Opcodes such as `OpCapbility`, `OpExtension` and type definitions are allowed inside a `spirv_asm` block. These instructions will be deduplicated and inserted into the correct sections defined by the SPIRV specification.
+You can also use the `&` prefix to refer to an l-value as a pointer-typed value in SPIRV, for example:
+```cpp
+float modf(float x, out float ip)
+{
+    return spirv_asm
+    {
+        result:$$float = OpExtInst glsl450 Modf $x &ip
+    };
+}
+```
 
-You may use SPIRV enum values directly as operands, for example:
+Opcodes such as `OpCapbility`, `OpExtension` and type definitions are allowed inside a `spirv_asm` block. These instructions will be deduplicated and inserted into the correct sections defined by the SPIRV specification, for example:
 ```cpp
-float spvAtomicAdd(__ref float value, float amount)
+uint4 WaveMatch(T value)
 {
     return spirv_asm
     {
-        OpExtension "SPV_EXT_shader_atomic_float_add";
-        OpCapability AtomicFloat32AddEXT;
-        result:$$float = OpAtomicFAddEXT &value Device None $amount
+        OpCapability GroupNonUniformPartitionedNV;
+        OpExtension "SPV_NV_shader_subgroup_partitioned";
+        OpGroupNonUniformPartitionNV $$uint4 result $value
+    };
+}
+```
+
+You may use SPIRV enum values directly as operands, for example:
+```cpp
+void memoryBarrierImage()
+{
+    spirv_asm
+    {
+        OpMemoryBarrier Device AcquireRelease|ImageMemory
     };
 }
 ```
diff --git a/source/slang/core.meta.slang b/source/slang/core.meta.slang
index c1eb2597a..db0acb3ed 100644
--- a/source/slang/core.meta.slang
+++ b/source/slang/core.meta.slang
@@ -697,6 +697,7 @@ struct Ptr
     __generic<TInt : __BuiltinIntegerType>
     __subscript(TInt index) -> T
     {
+        // If a 'Ptr[index]' is referred to by a '__ref', call 'kIROp_GetOffsetPtr(index)'
         __intrinsic_op($(kIROp_GetOffsetPtr))
         ref;
     }
@@ -1439,6 +1440,8 @@ struct OutputVertices
         // TODO: Make sure this remains write only, we can't do this with just
         // a 'set' operation as it's legal to only write to part of the output
         // buffer, or part of the output buffer at a time.
+        //
+        // If a 'OutputVertices[index]' is referred to by a '__ref', call 'kIROp_MeshOutputRef(index)'
         __intrinsic_op($(kIROp_MeshOutputRef))
         ref;
     }
@@ -1468,6 +1471,7 @@ struct OutputPrimitives
 {
     __subscript(uint index) -> T
     {
+        // If a 'OutputPrimitives[index]' is referred to by a '__ref', call 'kIROp_MeshOutputRef(index)'
         __intrinsic_op($(kIROp_MeshOutputRef))
         ref;
     }
diff --git a/source/slang/hlsl.meta.slang b/source/slang/hlsl.meta.slang
index 2e449b884..37d3ad19b 100644
--- a/source/slang/hlsl.meta.slang
+++ b/source/slang/hlsl.meta.slang
@@ -3071,7 +3071,10 @@ extension __TextureImpl<T,Shape,isArray,0,sampleCount,$(access),isShadow, 0,form
             }
         }
 
-        __intrinsic_op($(kIROp_ImageSubscript)) ref;
+        // If a 'Texture[location]' is referred to by a '__ref', call 'kIROp_ImageSubscript(location)'.
+        // This allows call's to stay aware that the input is from a 'Texture'.
+        __intrinsic_op($(kIROp_ImageSubscript)) 
+        ref;
     }
 }
 
@@ -3211,7 +3214,10 @@ extension __TextureImpl<T,Shape,isArray,1,sampleCount,$(access),isShadow, 0,form
             }
         }
 
-        __intrinsic_op($(kIROp_ImageSubscript)) ref;
+        // If a 'Texture[location, sampleIndex]' is referred to by a '__ref', call 'kIROp_ImageSubscript(location, sampleIndex)'.
+        // This allows call's to stay aware that the input is from a 'Texture'.
+        __intrinsic_op($(kIROp_ImageSubscript))
+        ref;
     }
 }
 
@@ -5314,6 +5320,9 @@ struct $(item.name)
     __generic<TIndex : __BuiltinIntegerType>
     __subscript(TIndex index) -> T
     {
+        // If a 'Buffer[index]' is referred to by a '__ref', call 'kIROp_RWStructuredBufferGetElementPtr(index)'.
+        //
+        // This allows call's to stay aware that the input is from a 'Buffer'.
         [__NoSideEffect]
         __intrinsic_op($(kIROp_RWStructuredBufferGetElementPtr))
         ref;
@@ -15420,6 +15429,8 @@ ${{{{
                 }
             }
 
+            // If a 'Texture[index]' is referred to by a '__ref', call 'kIROp_ImageSubscript(index)'.
+            // This allows call's to stay aware that the input is from a 'Texture'.
             __intrinsic_op($(kIROp_ImageSubscript))
             ref;
 ${{{{