Merge pull request #28417 from CodaFi/arcada

[Shepherd] Add documentation to _DependenceToken

Author: CodaFi

stdlib/public/core/ArrayShared.swift

@@ -9,8 +9,14 @@
 // See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
 //
 
-/// This type is used as a result of the _checkSubscript call to associate the
+/// This type is used as a result of the `_checkSubscript` call to associate the
 /// call with the array access call it guards.
+///
+/// In order for the optimizer see that a call to `_checkSubscript` is semantically
+/// associated with an array access, a value of this type is returned and later passed
+/// to the accessing function.  For example, a typical call to `_getElement` looks like
+///   let token = _checkSubscript(index, ...)
+///   return _getElement(index, ... , matchingSubscriptCheck: token)
 @frozen
 public struct _DependenceToken {
   @inlinable