[comment] Add a semantics note to SIL BindMemory

docs/SIL.rst

@@ -4363,11 +4363,22 @@ bind_memory
 Binds memory at ``Builtin.RawPointer`` value ``%0`` to type ``$T`` with enough
 capacity to hold ``%1`` values. See SE-0107: UnsafeRawPointer.
 
-Produces a opaque token representing the previous memory state. For
-memory binding semantics, this state includes the type that the memory
-was previously bound to. The token cannot, however, be used to
-retrieve a metatype. It's value is only meaningful to the Swift
-runtime for typed pointer verification.
+Produces a opaque token representing the previous memory state for
+memory binding semantics. This abstract state includes the type that
+the memory was previously bound to along with the size of the affected
+memory region, which can be derived from ``%1``. The token cannot, for
+example, be used to retrieve a metatype. It only serves a purpose when
+used by ``rebind_memory``, which has no static type information. The
+token dynamically passes type information from the first bind_memory
+into a chain of rebind_memory operations.
+
+Example::
+
+  %_      = bind_memory %0   : $Builtin.RawPointer, %numT : $Builtin.Word to $T // holds type 'T'
+  %token0 = bind_memory %0   : $Builtin.RawPointer, %numU : $Builtin.Word to $U // holds type 'U'
+  %token1 = rebind_memory %0 : $Builtin.RawPointer, %token0 : $Builtin.Word  // holds type 'T'
+  %token2 = rebind_memory %0 : $Builtin.RawPointer, %token1 : $Builtin.Word  // holds type 'U'
+
 
 rebind_memory
 `````````````
@@ -4386,8 +4397,8 @@ This instruction's semantics are identical to ``bind_memory``, except
 that the types to which memory will be bound, and the extent of the
 memory region is unknown at compile time. Instead, the bound-types are
 represented by a token that was produced by a prior memory binding
-operation. ``%in_token`` must be the result of bind_memory or
-rebind_memory.
+operation. ``%in_token`` must be the result of ``bind_memory`` or
+``rebind_memory``.
 
 begin_access
 ````````````

include/swift/SIL/SILInstruction.h

@@ -5048,7 +5048,14 @@ class ExplicitCopyAddrInst
 /// to hold %1 values.
 ///
 /// %token is an opaque word representing the previously bound types of this
-/// memory region, before binding it to a contiguous region of type $T.
+/// memory region, before binding it to a contiguous region of type $T. This
+/// token has no purpose unless it is consumed be a rebind_memory instruction.
+///
+/// Semantics: changes the type information assocated with a memory region. This
+/// affects all memory operations that alias with the given region of memory,
+/// regardless of their type or address provenance. For optimizations that query
+/// side effects, this is equivalent to writing and immediately reading an
+/// unknown value to memory at `%0` of `%1` bytes.
 class BindMemoryInst final : public InstructionBaseWithTrailingOperands<
                                  SILInstructionKind::BindMemoryInst,
                                  BindMemoryInst, SingleValueInstruction> {
@@ -5096,6 +5103,9 @@ class BindMemoryInst final : public InstructionBaseWithTrailingOperands<
 ///
 /// %out_token represents the previously bound types of this memory region,
 /// before binding it to %in_token.
+///
+/// This has the same semantics as bind_memory except that the size of memory
+/// affected must be derived from `%in_token`.
 class RebindMemoryInst final : public SingleValueInstruction {
   FixedOperandList<2> Operands;