[swift-users] Comprehensive documentation for Collection?

[Kyle Murray]

Meant to respond to the list with this reply:

The Index associated type used to show up on developer.apple.com. The way it’s declared changed between Swift 3.x and Swift 4.0 such that it doesn’t appear anymore. (It’s declared as part of _IndexableBase, where the underscore indicates that the type is intended to be an undocumented implementation detail: https://github.com/apple/swift/blob/master/docs/StdlibRationales.rst#protocols-with-restricted-conformance-rules)

On the current swift-4.1-branch, Index is declared directly on Collection, so it should start showing up again in the future.

-Kyle

> On Dec 15, 2017, at 10:06 PM, Howard Lovatt via swift-users <swift-users at swift.org> wrote:
> 
> It’s a problem with Apple documentation. swiftdoc.org does list the associated types, but is no longer maintained :(. 
> 
> -- Howard.
> 
>> On 16 Dec 2017, at 1:17 pm, Nevin Brackett-Rozinsky via swift-users <swift-users at swift.org> wrote:
>> 
>> In Xcode if I write,
>> 
>> extension Collection {
>>     var secondIndex: Index { return index(after: startIndex) }
>> }
>> 
>> and then option-click on “Index”, it shows “associatedtype Index : Comparable” followed by a description. Is this documented somewhere?
>> 
>> When I look at the documentation for Collection on developer.apple.com there is no mention of an Index associated type. I also don’t see it in The Swift Programming Language.
>> 
>> 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?
>> 
>> Also, are there any semantic requirements on Collection.Index, for example is it required that “idx < index(after: idx)” must evaluate to true for any valid index “idx”?
>> 
>> • • •
>> 
>> 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 documentation for it on developer.apple.com.
>> 
>> 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.
>> 
>> 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.
>> 
>> Nevin
>> _______________________________________________
>> swift-users mailing list
>> swift-users at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-users
> _______________________________________________
> swift-users mailing list
> swift-users at swift.org
> https://lists.swift.org/mailman/listinfo/swift-users
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-users/attachments/20171215/68ed0039/attachment.html>