[stdlib] Various documentation fixes #5723
Conversation
- Fix incorrect type in Float(_:String) examples - Expand discussions for ExpressibleBy_Literal protocols - Add notes about non-escaping unsafe pointers from closures - Add note about isEmpty to Collection.count discussions - Describe imported `Bool` types - Clean up some floating point discussions - Provide some additional operator documentation - Revise documentation for CVarArg functions - Fix incorrect Set method parameter descriptions - Clarify array bridging behavior - Add collection subscript complexity notes
|
@swift-ci Please smoke test |
|
@swift-ci Please smoke test |
1 similar comment
|
@swift-ci Please smoke test |
|
@airspeedswift OK to merge? |
|
@swift-ci Please smoke test |
| /// If the array grows larger than its capacity, it discards its current | ||
| /// storage and allocates a larger one. | ||
| /// If you add more elements to an array than it can hold with its current | ||
| /// capacity, it discards its current storage and allocates a larger one. |
There was a problem hiding this comment.
Something about the word storage being in the singular makes these read oddly to me.
There was a problem hiding this comment.
I borrowed a paragraph from the type discussion that better communicates this bit.
| @@ -97,6 +99,8 @@ public protocol _IndexableBase { | |||
| /// - Parameter bounds: A range of the collection's indices. The upper and | |||
| /// lower bounds of the `bounds` range must be valid indices of the | |||
| /// collection. | |||
| /// | |||
| /// - Complexity: O(1) | |||
There was a problem hiding this comment.
Is this agreed/inferred from somewhere else? Wonder if there are implementations where this is desirably not the case.
There was a problem hiding this comment.
I discussed this with Dave A—it's part of the intent of Collection and lots of other complexity guarantees depend on this being true.
| /// | ||
| /// let numberToFind: Int = 23 | ||
| /// let numberFromString: Int? = Int("23") // Optional(23) | ||
| /// if numberToFind == numberFromString { |
There was a problem hiding this comment.
I wonder if showing comparison to a literal would also help people "get" this i.e. numberFromString == 23
| /// is not an `Equatable` type, this operator allows matching against `nil`. | ||
| /// | ||
| /// var numbers: [Int]? | ||
| /// if nil ~= numbers { |
There was a problem hiding this comment.
Do we want to encourage people to do this? I think of this ~= as kind of an implementation detail of the switch usage (esp. given it takes an _ protocol as its arg).
| /// `numbers` variable as an optional array of integers. Although `Array<Int>` | ||
| /// is not an `Equatable` type, this operator allows matching against `nil`. | ||
| /// | ||
| /// var numbers: [Int]? |
There was a problem hiding this comment.
Not a huge fan of using implicit initial value of nil in our documentation (not a huge fan of this feature of the language tbh ;)
| /// | ||
| /// var numbers: [Int]? | ||
| /// if numbers == nil { | ||
| /// print("No numbers to be found.") |
There was a problem hiding this comment.
Using an optional array in an example also makes me nervous because of the whole empty-vs-nil thing. Can we maybe use an optional scalar instead?
There was a problem hiding this comment.
I changed these—when conditional conformance lands we would've needed to revisit these anyway, as [Int] will be Comparable then.
| /// Returns a subsequence by skipping elements while `predicate` returns | ||
| /// `true` and returning the remaining elements. | ||
| /// Returns a subsequence starting after the initial, consecutive elements | ||
| /// that satisfy the given predicate. |
There was a problem hiding this comment.
I feel like the original "skipping" wording was clearer regarding the possible consuming nature of this (a subsequence starting after" implies this is a "view" onto some underlying elements)
|
LGTM with these changes. |
|
@swift-ci Please smoke test and merge |
1 similar comment
|
@swift-ci Please smoke test and merge |
|
Thank you |
|
@swift-ci Please smoke test and merge |
This PR includes a variety of revisions to the standard library documentation:
Float(_:String)examplesExpressibleBy____LiteralprotocolsisEmptytoCollection.countdiscussionsBooltypesCVarArgfunctionsSetmethod parameter descriptions