averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-21 12:14:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

[stdlib] Clean up various documentation issues (#3804)

Browse Source 
* [stdlib] Clean up some documentation formatting

* [stdlib] Update example code for SE-0103

* [stdlib] Fix UnsafeBufferPointer documentation typo

* [stdlib] Collection documentation cleanup

* [stdlib] Fix String.init?(_:UTF16View) description

* [stdlib] Documentation fixes for SE-0091

* [stdlib] Add param info for String(repeating:count:)
This commit is contained in:
Nate Cook
2016-07-28 13:25:38 -05:00
committed by Ted Kremenek
parent 48c450eec1
commit 58fb4ef9c5
11 changed files with 83 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
stdlib/public/core/Collection.swift
View File

@@ -188,9 +188,6 @@ public protocol Indexable : IndexableBase {
/// to `index(before:)`.
///
/// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -234,9 +231,6 @@ public protocol Indexable : IndexableBase {
/// the method returns `nil`.
///
/// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -256,9 +250,6 @@ public protocol Indexable : IndexableBase {
/// collection conforms to the `BidirectionalCollection` protocol.
///
/// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -412,18 +403,18 @@ public struct IndexingIterator<
/// A sequence whose elements can be traversed multiple times,
/// nondestructively, and accessed by indexed subscript.
///
/// Collections are used extensively throughout the standard library. When
/// you use arrays, dictionaries, views of a string's contents and other
/// types, you benefit from the operations that the `Collection` protocol
/// declares and implements.
/// Collections are used extensively throughout the standard library. When you
/// use arrays, dictionaries, views of a string's contents and other types,
/// you benefit from the operations that the `Collection` protocol declares
/// and implements.
///
/// In addition to the methods that collections inherit from the `Sequence`
/// protocol, you gain access to methods that depend on accessing an element
/// at a specific position when using a collection.
///
/// For example, if you want to print only the first word in a string,
/// search for the index of the first space, and then create a subsequence up
/// to that position.
/// For example, if you want to print only the first word in a string, search
/// for the index of the first space and then create a subsequence up to that
/// position.
///
/// let text = "Buffalo buffalo buffalo buffalo."
/// if let firstSpace = text.characters.index(of: " ") {
@@ -464,24 +455,24 @@ public struct IndexingIterator<
/// print(firstChar)
/// // Prints "B"
///
/// The `Collection` protocol declares and provides default implementations
/// for many operations that depend on elements being accessible by their
/// subscript. For example, you can also access the first character of
/// `text` using the `first` property, which has the value of the first
/// element of the collection, or `nil` if the collection is empty.
/// The `Collection` protocol declares and provides default implementations for
/// many operations that depend on elements being accessible by their
/// subscript. For example, you can also access the first character of `text`
/// using the `first` property, which has the value of the first element of
/// the collection, or `nil` if the collection is empty.
///
/// print(text.characters.first)
/// // Prints "Optional("B")"
///
/// Traversing a Collection
/// Traversing a Collection
/// =======================
///
/// While a sequence may be consumed as it is traversed, a collection is
/// guaranteed to be multi-pass: Any element may be repeatedly accessed by
/// saving its index. Moreover, a collection's indices form a finite range
/// of the positions of the collection's elements. This guarantees the
/// safety of operations that depend on a sequence being finite, such as
/// checking to see whether a collection contains an element.
/// Although a sequence can be consumed as it is traversed, a collection is
/// guaranteed to be multipass: Any element may be repeatedly accessed by
/// saving its index. Moreover, a collection's indices form a finite range of
/// the positions of the collection's elements. This guarantees the safety of
/// operations that depend on a sequence being finite, such as checking to see
/// whether a collection contains an element.
///
/// Iterating over the elements of a collection by their positions yields the
/// same elements in the same order as iterating over that collection using
@@ -498,7 +489,7 @@ public struct IndexingIterator<
/// // Prints "i"
/// // Prints "f"
/// // Prints "t"
///
///
/// for i in word.characters.indices {
/// print(word.characters[i])
/// }
@@ -508,26 +499,28 @@ public struct IndexingIterator<
/// // Prints "f"
/// // Prints "t"
///
/// Conforming to the Collection Protocol
/// Conforming to the Collection Protocol
/// =====================================
///
/// If you create a custom sequence that can provide repeated access to its
/// elements, conformance to the `Collection` protocol gives your custom type
/// a more useful and more efficient interface for sequence and collection
/// operations. To add `Collection` conformance to your type, declare
/// `startIndex` and `endIndex` properties, a subscript that provides at least
/// read-only access to your type's elements, and the `index(after:)` method
/// for advancing your collection's indices.
/// elements, make sure that its type conforms to the `Collection` protocol in
/// order to give a more useful and more efficient interface for sequence and
/// collection operations. To add `Collection` conformance to your type, you
/// must declare at least the four following requirements:
///
/// - the `startIndex` and `endIndex` properties,
/// - a subscript that provides at least read-only access to your type's
/// elements, and
/// - the `index(after:)` method for advancing an index into your collection.
///
/// Expected Performance
/// ====================
///
/// Types that conform to `Collection` are expected to provide the
/// `startIndex` and `endIndex` properties and subscript access to elements
/// as O(1) operations. Types that are not able to guarantee that expected
/// performance must document the departure, because many collection operations
/// depend on O(1) subscripting performance for their own performance
/// guarantees.
/// Types that conform to `Collection` are expected to provide the `startIndex`
/// and `endIndex` properties and subscript access to elements as O(1)
/// operations. Types that are not able to guarantee that expected performance
/// must document the departure, because many collection operations depend on
/// O(1) subscripting performance for their own performance guarantees.
///
/// The performance of some collection operations depends on the type of index
/// that the collection provides. For example, a random-access collection,
@@ -696,7 +689,6 @@ public protocol Collection : Indexable, Sequence {
/// `start` must be a valid index of the collection.
/// - Returns: A subsequence starting at the `start` position.
///
/// - Precondition: `start >= self.startIndex && start <= self.endIndex`
/// - Complexity: O(1)
func suffix(from start: Index) -> SubSequence
@@ -790,9 +782,6 @@ public protocol Collection : Indexable, Sequence {
/// to `index(before:)`.
///
/// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -836,9 +825,6 @@ public protocol Collection : Indexable, Sequence {
/// the method returns `nil`.
///
/// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -856,8 +842,8 @@ public protocol Collection : Indexable, Sequence {
/// - end: Another valid index of the collection. If `end` is equal to
/// `start`, the result is zero.
/// - Returns: The distance between `start` and `end`. The result can be
/// negative only if the collection conforms to the `BidirectionalCollection`
/// protocol.
/// negative only if the collection conforms to the
/// `BidirectionalCollection` protocol.
///
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the
@@ -926,9 +912,6 @@ extension Indexable {
/// to `index(before:)`.
///
/// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -974,9 +957,6 @@ extension Indexable {
/// the method returns `nil`.
///
/// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -998,9 +978,6 @@ extension Indexable {
/// collection conforms to the `BidirectionalCollection` protocol.
///
/// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
/// - Precondition:
/// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
/// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
/// value of `n`.
@@ -1414,7 +1391,6 @@ extension Collection {
/// `end` must be a valid index of the collection.
/// - Returns: A subsequence up to, but not including, the `end` position.
///
/// - Precondition: `end >= self.startIndex && end <= self.endIndex`
/// - Complexity: O(1)
/// - SeeAlso: `prefix(through:)`
public func prefix(upTo end: Index) -> SubSequence {
@@ -1442,7 +1418,6 @@ extension Collection {
/// subsequence. `start` must be a valid index of the collection.
/// - Returns: A subsequence starting at the `start` position.
///
/// - Precondition: `start >= self.startIndex && start <= self.endIndex`
/// - Complexity: O(1)
public func suffix(from start: Index) -> SubSequence {
return self[start..<endIndex]

21
stdlib/public/core/Comparable.swift
View File

@@ -63,12 +63,13 @@
/// - `a < b` and `b < c` implies `a < c` (Transitivity)
///
/// To add `Comparable` conformance to your custom types, define the `<` and
/// `==` operators. The `==` operator is a requirement of the `Equatable`
/// protocol, which `Comparable` extends---see that protocol's documentation
/// for more information about equality in Swift. Because default
/// implementations of the remainder of the relational operators are provided
/// by the standard library, you'll be able to use `!=`, `>`, `<=`, and `>=`
/// with instances of your type without any further code.
/// `==` operators as static methods of your types. The `==` operator is a
/// requirement of the `Equatable` protocol, which `Comparable` extends---see
/// that protocol's documentation for more information about equality in
/// Swift. Because default implementations of the remainder of the relational
/// operators are provided by the standard library, you'll be able to use
/// `!=`, `>`, `<=`, and `>=` with instances of your type without any further
/// code.
///
/// As an example, here's an implementation of a `Date` structure that stores
/// the year, month, and day of a date:
@@ -92,7 +93,6 @@
/// return lhs.day < rhs.day
/// }
/// }
/// }
///
/// This function uses the least specific nonmatching property of the date to
/// determine the result of the comparison. For example, if the two `year`
@@ -102,9 +102,10 @@
/// Next, implement the `==` operator function, the requirement inherited from
/// the `Equatable` protocol.
///
/// func == (lhs: Date, rhs: Date) -> Bool {
/// return lhs.year == rhs.year && lhs.month == rhs.month
/// && lhs.day == rhs.day
/// static func == (lhs: Date, rhs: Date) -> Bool {
/// return lhs.year == rhs.year && lhs.month == rhs.month
/// && lhs.day == rhs.day
/// }
/// }
///
/// Two `Date` instances are equal if each of their corresponding properties is

12
stdlib/public/core/CompilerProtocols.swift
View File

@@ -262,7 +262,7 @@ public protocol _ExpressibleByBuiltinUnicodeScalarLiteral {
/// // Prints "ñ"
///
/// Conforming to ExpressibleByUnicodeScalarLiteral
/// =============================================
/// ===============================================
///
/// To add `ExpressibleByUnicodeScalarLiteral` conformance to your custom type,
/// implement the required initializer.
@@ -305,7 +305,7 @@ public protocol _ExpressibleByBuiltinExtendedGraphemeClusterLiteral
/// // Prints "❄︎"
///
/// Conforming to ExpressibleByExtendedGraphemeClusterLiteral
/// =======================================================
/// =========================================================
///
/// To add `ExpressibleByExtendedGraphemeClusterLiteral` conformance to your
/// custom type, implement the required initializer.
@@ -349,7 +349,7 @@ public protocol _ExpressibleByBuiltinUTF16StringLiteral
/// let picnicGuest = "Deserving porcupine"
///
/// Conforming to ExpressibleByStringLiteral
/// ======================================
/// ========================================
///
/// To add `ExpressibleByStringLiteral` conformance to your custom type,
/// implement the required initializer.
@@ -456,7 +456,7 @@ public protocol ExpressibleByStringLiteral
/// // Prints "Zero integers: []"
///
/// Conforming to ExpressibleByArrayLiteral
/// =====================================
/// =======================================
///
/// Add the capability to be initialized with an array literal to your own
/// custom types by declaring an `init(arrayLiteral:)` initializer. The
@@ -514,7 +514,7 @@ public protocol ExpressibleByArrayLiteral {
/// by assigning an instance of one of these types.
///
/// Conforming to the ExpressibleByDictionaryLiteral Protocol
/// =======================================================
/// =========================================================
///
/// To add the capability to be initialized with a dictionary literal to your
/// own custom types, declare an `init(dictionaryLiteral:)` initializer. The
@@ -565,7 +565,7 @@ public protocol ExpressibleByDictionaryLiteral {
/// // Prints "One cookie: $2, 3 cookies: $6."
///
/// Conforming to the ExpressibleByStringInterpolation Protocol
/// =========================================================
/// ===========================================================
///
/// To use string interpolation to initialize instances of your custom type,
/// implement the required initializers for `ExpressibleByStringInterpolation`

20
stdlib/public/core/Equatable.swift
View File

@@ -48,10 +48,10 @@
/// `Comparable` protocols, which allow more uses of your custom type, such as
/// constructing sets or sorting the elements of a collection.
///
/// To adopt the `Equatable` protocol, implement the equal-to operator (`==`).
/// The standard library provides an implementation for the not-equal-to
/// operator (`!=`) for any `Equatable` type, which calls the custom `==`
/// function and negates its result.
/// To adopt the `Equatable` protocol, implement the equal-to operator (`==`)
/// as a static method of your type. The standard library provides an
/// implementation for the not-equal-to operator (`!=`) for any `Equatable`
/// type, which calls the custom `==` function and negates its result.
///
/// As an example, consider a `StreetAddress` structure that holds the parts of
/// a street address: a house or building number, the street name, and an
@@ -76,12 +76,12 @@
/// `Equatable`.
///
/// extension StreetAddress: Equatable {
/// static func == (lhs: StreetAddress, rhs: StreetAddress) -> Bool {
/// return
/// lhs.number == rhs.number &&
/// lhs.street == rhs.street &&
/// lhs.unit == rhs.unit
/// }
/// static func == (lhs: StreetAddress, rhs: StreetAddress) -> Bool {
/// return
/// lhs.number == rhs.number &&
/// lhs.street == rhs.street &&
/// lhs.unit == rhs.unit
/// }
/// }
///
/// The `StreetAddress` type now conforms to `Equatable`. You can use `==` to

1
stdlib/public/core/HashedCollections.swift.gyb
View File

@@ -368,7 +368,6 @@ internal struct _UnmanagedAnyObjectArray {
/// print(primes.intersection(favoriteNumbers))
/// // Prints "[5, 7]"
///
///
/// Sequence and Collection Operations
/// ==================================
///

2
stdlib/public/core/LazySequence.swift
View File

@@ -47,7 +47,7 @@
/// /// - Complexity: O(N)
/// func scan<ResultElement>(
/// _ initial: ResultElement,
/// _ nextPartialResult: @noescape (ResultElement, Iterator.Element) -> ResultElement
/// _ nextPartialResult: (ResultElement, Iterator.Element) -> ResultElement
/// ) -> [ResultElement] {
/// var result = [initial]
/// for x in self {

6
stdlib/public/core/Policy.swift
View File

@@ -343,7 +343,7 @@ public typealias AnyClass = AnyObject.Type
/// let z = x | y // 0b00001111
///
/// Performing a bitwise OR operation with a value and `allZeros` always
/// returns the same value.
/// returns the same value.
///
/// print(x | .allZeros) // 0b00000101
/// // Prints "5"
@@ -357,7 +357,7 @@ public typealias AnyClass = AnyObject.Type
/// let z = x & y // 0b00000100
///
/// Performing a bitwise AND operation with a value and `allZeros` always
/// returns `allZeros`.
/// returns `allZeros`.
///
/// print(x & .allZeros) // 0b00000000
/// // Prints "0"
@@ -372,7 +372,7 @@ public typealias AnyClass = AnyObject.Type
/// let z = x ^ y // 0b00001011
///
/// Performing a bitwise XOR operation with a value and `allZeros` always
/// returns the same value.
/// returns the same value.
///
/// print(x ^ .allZeros) // 0b00000101
/// // Prints "5"

11
stdlib/public/core/Sequence.swift
View File

@@ -60,11 +60,10 @@
/// more idiomatic approach to traversing a sequence in Swift. Some
/// algorithms, however, may call for direct iterator use.
///
/// One example is the `reduce1(_:)` method. Similar to the
/// `reduce(_:)` method defined in the standard
/// library, which takes an initial value and a combining closure,
/// `reduce1(_:)` uses the first element of the sequence as the
/// initial value.
/// One example is the `reduce1(_:)` method. Similar to the `reduce(_:)` method
/// defined in the standard library, which takes an initial value and a
/// combining closure, `reduce1(_:)` uses the first element of the sequence as
/// the initial value.
///
/// Here's an implementation of the `reduce1(_:)` method. The sequence's
/// iterator is used directly to retrieve the initial value before looping
@@ -72,7 +71,7 @@
///
/// extension Sequence {
/// func reduce1(
/// _ nextPartialResult: (Iterator.Element, Iterator.Element) -> Iterator.Element
/// _ nextPartialResult: (Iterator.Element, Iterator.Element) -> Iterator.Element
/// ) -> Iterator.Element?
/// {
/// var i = makeIterator()

10
stdlib/public/core/StringLegacy.swift
View File

@@ -36,14 +36,13 @@ extension String {
/// let zeroes = String("0" as UnicodeScalar, count: 10)
/// print(zeroes)
/// // Prints "0000000000"
@available(*, unavailable, message: "Replaced by init(repeating: String, count: Int)")
public init(repeating repeatedValue: UnicodeScalar, count: Int) {
Builtin.unreachable()
}
/// Creates a string representing the given string repeated the
/// specified number of times.
/// Creates a new string representing the given string repeated the specified
/// number of times.
///
/// For example, use this initializer to create a string with ten `"00"`
/// strings in a row.
@@ -51,6 +50,11 @@ extension String {
/// let zeroes = String(repeating: "00", count: 10)
/// print(zeroes)
/// // Prints "00000000000000000000"
///
/// - Parameters:
/// - repeatedValue: The string to repeat.
/// - count: The number of times to repeat `repeatedValue` in the resulting
/// string.
public init(repeating repeatedValue: String, count: Int) {
if count == 0 {
self = ""

2
stdlib/public/core/StringUTF16.swift
View File

@@ -318,7 +318,7 @@ extension String {
}
}
/// Creates a string corresponding to the given sequence of UTF-8 code units.
/// Creates a string corresponding to the given sequence of UTF-16 code units.
///
/// If `utf16` contains unpaired UTF-16 surrogates, the result is `nil`.
///

4
stdlib/public/core/UnsafeBufferPointer.swift.gyb
View File

@@ -31,8 +31,8 @@ public struct UnsafeBufferPointerIterator<Element>
}
%for Mutable in ('Mutable', ''):
/// A non-owning pointer to buffer of ${Mutable.lower()} `Element`s stored
/// contiguously in memory, presenting a `Collection` interface to the
/// A non-owning pointer to a buffer of ${Mutable.lower()} elements stored
/// contiguously in memory, presenting a collection interface to the
/// underlying elements.
///
/// The pointer should be aligned to `alignof(Element.self)`.