[stdlib] Various documentation improvements #9574
Conversation
* abstracts for integer types * fixed discussions for floating-point operators
* removing .characters from examples * beginning new String doc revisions * improvements to the String Foundation overlay docs * minor revisions elsewhere
* documented swap(_:_:) and MutableCollection.swapAt(_:_:) * clarifications and fixes elsewhere
* finish string documentation revisions * revise examples throughout to use range expressions instead of e.g. prefix(upTo: _)
|
@swift-ci Please smoke test |
| @@ -151,7 +151,7 @@ if True: | |||
| /// Here's an implementation of those steps: | |||
| /// | |||
| /// if let i = absences.index(where: { $0 > 0 }) { // 1 | |||
| /// let absencesAfterFirst = absences.suffix(from: i + 1) // 2 | |||
| /// let absencesAfterFirst = absences[(i + 1)...] // 2 | |||
There was a problem hiding this comment.
absences[i+1...] will work without the extra parens. I personally think cases like this read better without spaces around the +, but you can always do absences[i + 1...] or absences[i + 1 ...] if you must have them. The middle one is actually quite good too; I might switch to doing that.
There was a problem hiding this comment.
None of those syntaxes work for me; the parens seem to be necessary. We could add a + overload for a CountablePartialRangeFrom<Bound> and Bound.Stride okay I'll see myself out…
There was a problem hiding this comment.
Oh, rats. Yes, they are necessary because only binary operators have precedence, and unary operators bind more tightly. That rots:
i+1...j-1 // OK
i+1... // Error :(“Someone” should file a Jira.
There was a problem hiding this comment.
stdlib/public/core/Arrays.swift.gyb
Outdated
| @@ -170,7 +170,7 @@ if True: | |||
| """ | |||
| elif Self == 'Array': | |||
| SelfDocComment = '''\ | |||
| /// An ordered, random-access collection. | |||
| /// An ordered, random-access collection of elements of a single type. | |||
There was a problem hiding this comment.
That's not accurate, is it? They have a single static type, but of course you can have [Any] and then the types can be as diverse as you like. I don't think it helps unless we're really trying to hide the fact that things like [Any] exist.
There was a problem hiding this comment.
I'm going to take that back out until I think of a clearer way to express it that doesn't pretend [Any] doesn't exist.
stdlib/public/core/Character.swift
Outdated
| /// | ||
| /// let greeting = "Hello! 🐥" | ||
| /// print("Character count: \(greeting.characters.count)") | ||
| /// print("Character count: \(greeting.count)") |
stdlib/public/core/Collection.swift
Outdated
| /// // Prints "Buffalo" | ||
| /// | ||
| /// You can retrieve the same slice using other methods, such as finding the | ||
| /// terminating index, and then using the `prefix(upTo:)` method, which takes | ||
| /// an index as its parameter, or by using the view's ranged subscript. | ||
| /// terminating index, and the using the string's ranged subscript, or by |
There was a problem hiding this comment.
the: typo?
IMO "ranged subscript" is not as good a term as "slicing operation"
There was a problem hiding this comment.
Thanks! I like "slicing operation," too—going to wait and handle that one on a more holistic basis, though.
stdlib/public/core/Collection.swift
Outdated
| /// terminating index, and then using the `prefix(upTo:)` method, which takes | ||
| /// an index as its parameter, or by using the view's ranged subscript. | ||
| /// terminating index, and the using the string's ranged subscript, or by | ||
| /// using the `prefix(upTo:)` method, which takes an index as its parameter. |
There was a problem hiding this comment.
I think you should drop mention of that; IMO we'll probably obsolete (or at least deprecate) it for Swift 4
|
@swift-ci Please smoke test |
[stdlib] Various documentation improvements
prefix(upTo: _)swap(_:_:)andMutableCollection.swapAt(_:_:).charactersfrom examples