[stdlib] improve documentation of withContiguous[Mutable]StorageIfAvailable

- clarify the requirement that the entire collection must be accessible
- clarify the requirement surrounding subsequences / slices
- add parameter descriptions
- specify that buffer cannot be replaced

Author: glessard

stdlib/public/core/MutableCollection.swift

@@ -172,34 +172,53 @@ where SubSequence: MutableCollection
   ///
   /// - Complexity: O(1)
   mutating func swapAt(_ i: Index, _ j: Index)
-  
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// mutable contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of mutable contiguous storage, `body` is not
+
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// mutable storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous mutable storage, `body` is not
   /// called and `nil` is returned.
   ///
-  /// Often, the optimizer can eliminate bounds- and uniqueness-checks
-  /// within an algorithm, but when that fails, invoking the
-  /// same algorithm on `body`\ 's argument lets you trade safety for
-  /// speed.
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
+  /// A `Collection` that provides its own implementation of this method
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// mutable storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
   @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R?
 
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// mutable contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of mutable contiguous storage, `body` is not
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// mutable storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous mutable storage, `body` is not
   /// called and `nil` is returned.
   ///
-  /// Often, the optimizer can eliminate bounds- and uniqueness-checks
-  /// within an algorithm, but when that fails, invoking the
-  /// same algorithm on `body`\ 's argument lets you trade safety for
-  /// speed.
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
+  /// A `Collection` that provides its own implementation of this method
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// mutable storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
+  ///
+  /// - Note: `buffer` must not be replaced by `body`.
+  ///
+  /// - Parameters:
+  ///   - body: a closure to be executed using the elements of this collection.
+  ///   - buffer: a buffer to the mutable contiguous storage of this collection.
+  /// - Returns: the value returned by `body`, or `nil`.
   mutating func withContiguousMutableStorageIfAvailable<R>(
-    _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
+    _ body: (_ buffer: inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R?
 }
 

stdlib/public/core/Sequence.swift

@@ -383,20 +383,31 @@ public protocol Sequence {
   __consuming func _copyContents(
     initializing ptr: UnsafeMutableBufferPointer<Element>
   ) -> (Iterator,UnsafeMutableBufferPointer<Element>.Index)
-  
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of contiguous storage, `body` is not
+
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous storage, `body` is not
   /// called and `nil` is returned.
   ///
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
   /// A `Collection` that provides its own implementation of this method
-  /// must also guarantee that an equivalent buffer of its `SubSequence` 
-  /// can be generated by advancing the pointer by the distance to the
-  /// slice's `startIndex`.
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
+  ///
+  /// - Parameters:
+  ///   - body: a closure to be executed using the elements of this collection.
+  ///   - buffer: a buffer to the contiguous storage of this collection.
+  /// - Returns: the value returned by `body`, or `nil`.
   func withContiguousStorageIfAvailable<R>(
-    _ body: (UnsafeBufferPointer<Element>) throws -> R
-  ) rethrows -> R?  
+    _ body: (_ buffer: UnsafeBufferPointer<Element>) throws -> R
+  ) rethrows -> R?
 }
 
 // Provides a default associated type witness for Iterator when the