<div dir="ltr">In Xcode if I write,<div><br></div><div><div><font face="monospace, monospace">extension Collection {</font></div><div><font face="monospace, monospace">    var secondIndex: Index { return index(after: startIndex) }</font></div><div><font face="monospace, monospace">}</font></div></div><div><br></div><div>and then option-click on “Index”, it shows “associatedtype Index : Comparable” followed by a description. Is this documented somewhere?</div><div><br></div><div>When I look at the <a href="https://developer.apple.com/documentation/swift/collection" target="_blank">documentation for Collection</a> on <a href="http://developer.apple.com">developer.apple.com</a> there is no mention of an Index associated type. I also don’t see it in The Swift Programming Language.</div><div><br></div><div>If someone didn’t already know Collection.Index exists, how would they be expected to learn of it? And if they didn’t know it must be Comparable how would they learn that?</div><div><br></div><div>Also, are there any semantic requirements on Collection.Index, for example is it required that “idx &lt; index(after: idx)” must evaluate to true for any valid index “idx”?</div><div><br></div><div>• • •</div><div><br></div><div>On a somewhat related note, the “indices” property of Collection has a discussion section visible by option-clicking in Xcode or by looking at the <a href="https://developer.apple.com/documentation/swift/collection/1641719-indices">documentation for it</a> on <a href="http://developer.apple.com">developer.apple.com</a>.</div><div><br></div><div>And that discussion recommends against iterating over “indices” when mutating a collection, because “indices” could hold a strong reference to the collection and thus create an unexpected copy. Instead one should manually advance from startIndex to endIndex in a while loop.</div><div><br></div><div>Now, this is at least documented, but perhaps it should be made more prominent? It seems to me that if “for i in c.indices” represents a performance pitfall then it should be regarded as an attractive nuisance.</div><div><br></div><div>Nevin</div></div>