Add descriptive doc comments to withMemoryRebound(to:capacity:_:) and… (#5072)

* Add descriptive doc comments to withMemoryRebound(to:capacity:_:) and bindMemory(to:capacity:).

SR-2480: Improve documentation for withMemoryRebound(to:capacity:_:)
rdar://problem/28440528

* Nate's feedback

Author: atrick

stdlib/public/core/UnsafePointer.swift.gyb

@@ -366,12 +366,25 @@ public struct ${Self}<Pointee>
 %  end
 
   /// Rebinds memory at `self` to type `T` with capacity to hold `count`
-  /// adjacent `T` values while executing the `body` closure. After executing
-  /// the closure, rebinds memory back to `Pointee`.
+  /// adjacent `T` values while executing the `body` closure.
+  ///
+  /// After executing the closure, rebinds memory back to `Pointee`.
   ///
   /// - Precondition: Type 'T' is layout compatible with type 'Pointee'.
   /// - Precondition: The memory `self..<self + count * MemoryLayout<T>.stride`
   ///   is bound to `Pointee`.
+  ///
+  /// Accessing `${Self}<T>.pointee` requires that the memory be "bound" to
+  /// type `T`.  A memory location may only be bound to one type at a time, so
+  /// accessing the same memory as an unrelated type without first rebinding the
+  /// memory is undefined. `self` may not be accessed within the `body` closure
+  /// because memory is no longer bound to `Pointee` while it executes. The
+  /// closure's `${Self}<T>` argument must not escape the closure because memory
+  /// is only temporarily bound to `T`.
+  ///
+  /// To persistently bind this memory to a different type, first obtain a
+  /// raw pointer to the memory, then invoke the `bindMemory` API:
+  /// `UnsafeRawPointer(typedPointer).bindMemory(to:capacity:)`.
   public func withMemoryRebound<T, Result>(to: T.Type, capacity count: Int,
     _ body: (${Self}<T>) throws -> Result
   ) rethrows -> Result {

stdlib/public/core/UnsafeRawPointer.swift.gyb

@@ -173,8 +173,9 @@ public struct Unsafe${Mutable}RawPointer : Strideable, Hashable, _Pointer {
   ///   that is layout compatible with `T`.
   /// - Postcondition: The memory is bound to 'T' starting at `self` continuing
   ///   through `self` + `count` * `MemoryLayout<T>.stride`
-  /// - Warning: Binding memory to a type is potentially undefined if the
-  ///   memory is ever accessed as an unrelated type.
+  /// - Warning: A memory location may only be bound to one type at a time.
+  ///   The behavior of accessing memory as type `U` while it is bound to an
+  ///   unrelated type `T` is undefined.
   @_transparent
   @discardableResult
   public func bindMemory<T>(to type: T.Type, capacity count: Int)