[stdlib] Change post-nil guarantee for IteratorProtocol.next()

[PatrickPijnappel]

What's in this pull request?

Swift evolution proposal: swiftlang/swift-evolution#213
Swift evolution thread: http://thread.gmane.org/gmane.comp.lang.swift.evolution/focus=8519
Update from #1544 to resolve conflicts with master.

Changes the guarantee for IteratorProtocol.next() to:

/// Advance to the next element and return it, or `nil` if no next element
/// exists.  Once `nil` has been returned, all subsequent calls return `nil`.
///
/// - Precondition: `next()` has not been applied to a copy of `self`
///   since the copy was made.

All IteratorType implementations in the standard library already comply.

[lattner]

SE-0052 is accepted, @dabrahams or @gribozavr, can you please review this? Thanks!

[lattner]

Oh, also @PatrickPijnappel it looks like this patch has conflicts. Can you please update it when you get a chance? Thanks!

[gribozavr]

The wording LGTM, but I'd like @dabrahams to also take a look.

[PatrickPijnappel]

@lattner @gribozavr Ok, resolved the conflicts!

• The first line of the docs in IteratorProtocol diverged a bit, but wasn't consistent with the docs for the implementations. I used the original formulation in this commit.
• Also I standardized the docs on 'advances/returns' vs. the 'advance/return' which half of them used (as I understand it the former is the preferred style?).

[gribozavr]

CC @natecook1000 for the documentation style.

[natecook1000]

The documentation style ('advances' instead of 'advance') is right on. I think describing the nil-returning behavior in the IteratorProtocol documentation should be sufficient, though—does that note need to be on every iterator?

This paragraph could use a note about the behavior, too, since it's giving instructions about how to implement an iterator: https://github.com/apple/swift/pull/1702/files#diff-b9ba8d4ad76ba94c1eeabc504d582b57R120

[dabrahams]

on Wed May 04 2016, Dmitri Gribenko <notifications-AT-github.aaakk.us.kg> wrote:

The wording LGTM, but I'd like @dabrahams to also take a look.

The summary should be a single sentence fragment; see
https://swift.org/documentation/api-design-guidelines/#write-doc-comment

Dave

[PatrickPijnappel]

@natecook1000 I'd say the nil behavior and the non-copy requirement are important for consumers of the API (is there a guideline on this?), though defintely I agree they should not be in the summary line. I'm out at the moment but will adjust on Monday!

[PatrickPijnappel]

@dabrahams Ok moved the guarantee away from the summary, so that's now a single line!

[PatrickPijnappel]

@natecook1000 @dabrahams Is there a guideline on what information in the protocol's doc comment is restated in the implementation's doc comment btw?

[dabrahams]

No such guideline exists. BTW, I was not saying you should move that information out of the summary (nor was I saying you shouldn’t); if it belongs in the summary you can use a semicolon to join the parts instead of a period.

[PatrickPijnappel]

@dabrahams Is there still something blocking this?

[gribozavr]

@natecook1000 Could you review, please?

[natecook1000]

@gribozavr LGTM

[gribozavr]

@swift-ci Please test and merge

[PatrickPijnappel]

@gribozavr Build seems to have failed on an unrelated issue.

[gribozavr]

Indeed. What I want to test is that SourceKit tests (which sometimes include snippets of the doc comments) are not affected by this change.

[gribozavr]

@swift-ci Please smoke test

[gribozavr]

Tests have passed, merging!