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, 27 insertions, 7 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
     };
 }
 ```