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>

2 files changed, 17 insertions, 2 deletions

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;
 ${{{{