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>

1 files changed, 4 insertions, 0 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;
     }