[stdlib] Revise documentation for string-related types & protocols (#2644)

* [stdlib] Revise documentation for string-related types

This documentation revision covers a large number of types & protocols:
String, its views and their indices, the Unicode codec types and protocol,
as well as Character, UnicodeScalar, and StaticString, among others.

This also includes a few small changes across the standard library for
consistency.

Cherry-picked and merged from 44b2d56

* [stdlib] Update tests for new String documentation

In addition to a new test fixture for 'SourceKit/DocSupport/
doc_clang_module.swift', this removes the check for an ASCII-only
generated standard library interface from 'SourceKit/InterfaceGen/
gen_stdlib.swift'.

Cherry-picked from dee12dc

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -482,8 +482,8 @@ public struct ${Self}<Element>
 %end
   }
 
-  /// The array's "past the end" position, or one greater than the last valid
-  /// subscript argument.
+  /// The array's "past the end" position---that is, the position one greater
+  /// than the last valid subscript argument.
   ///
   /// When you need a range that includes the last element of an array, use the
   /// half-open range operator (`..<`) with `endIndex`. The `..<` operator
@@ -946,7 +946,7 @@ extension ${Self} : ArrayLiteralConvertible {
   // Optimized implementation for Array
   /// Creates an array from the given array literal.
   ///
-  /// Don't directly call this initializer, which is used by the compiler
+  /// Do not call this initializer directly. It is used by the compiler
   /// when you use an array literal. Instead, create a new array by using an
   /// array literal as its value. To do this, enclose a comma-separated list of
   /// values in square brackets.
@@ -963,7 +963,7 @@ extension ${Self} : ArrayLiteralConvertible {
 %else:
   /// Creates an array from the given array literal.
   ///
-  /// Don't directly call this initializer, which is used by the compiler when
+  /// Do not call this initializer directly. It is used by the compiler when
   /// you use an array literal. Instead, create a new array by using an array
   /// literal as its value. To do this, enclose a comma-separated list of
   /// values in square brackets.

stdlib/public/core/Bool.swift

@@ -79,7 +79,7 @@ extension Bool : _BuiltinBooleanLiteralConvertible, BooleanLiteralConvertible {
 
   /// Creates an instance initialized to the specified Boolean literal.
   ///
-  /// Don't directly call this initializer, which is used by the compiler when
+  /// Do not call this initializer directly. It is used by the compiler when
   /// you use a Boolean literal. Instead, create a new `Bool` instance by
   /// using one of the Boolean literals `true` and `false`.
   ///

stdlib/public/core/CString.swift

@@ -16,25 +16,64 @@ import SwiftShims
 
 extension String {
 
-  /// Create a new `String` by copying the nul-terminated UTF-8 data
-  /// referenced by a `cString`.
+  /// Creates a new string by copying the null-terminated UTF-8 data referenced
+  /// by the given pointer.
   ///
-  /// If `cString` contains ill-formed UTF-8 code unit sequences, replaces them
-  /// with replacement characters (U+FFFD).
+  /// If `cString` contains ill-formed UTF-8 code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
   ///
-  /// - Precondition: `cString != nil`
+  /// The following example calls this initializer with pointers to the
+  /// contents of two different `CChar` arrays---the first with well-formed
+  /// UTF-8 code unit sequences and the second with an ill-formed sequence at
+  /// the end.
+  ///
+  ///     let validUTF8: [CChar] = [67, 97, 102, -61, -87, 0]
+  ///     validUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(cString: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Café"
+  ///
+  ///     let invalidUTF8: [CChar] = [67, 97, 102, -61, 0]
+  ///     invalidUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(cString: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Caf�"
+  ///
+  /// - Parameter cString: A pointer to a null-terminated UTF-8 code sequence.
   public init(cString: UnsafePointer<CChar>) {
     self = String.decodeCString(UnsafePointer(cString), as: UTF8.self,
       repairingInvalidCodeUnits: true)!.result
   }
 
-  /// Create a new `String` by copying the nul-terminated UTF-8 data
-  /// referenced by a `cString`.
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given pointer.
+  ///
+  /// This initializer does not try to repair ill-formed UTF-8 code unit
+  /// sequences. If any are found, the result of the initializer is `nil`.
+  ///
+  /// The following example calls this initializer with pointers to the
+  /// contents of two different `CChar` arrays---the first with well-formed
+  /// UTF-8 code unit sequences and the second with an ill-formed sequence at
+  /// the end.
+  ///
+  ///     let validUTF8: [CChar] = [67, 97, 102, -61, -87, 0]
+  ///     validUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(validatingUTF8: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Optional(Café)"
   ///
-  /// Does not try to repair ill-formed UTF-8 code unit sequences, fails if any
-  /// such sequences are found.
+  ///     let invalidUTF8: [CChar] = [67, 97, 102, -61, 0]
+  ///     invalidUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(validatingUTF8: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "nil"
   ///
-  /// - Precondition: `cString != nil`
+  /// - Parameter cString: A pointer to a null-terminated UTF-8 code sequence.
   public init?(validatingUTF8 cString: UnsafePointer<CChar>) {
     guard let (result, _) = String.decodeCString(
         UnsafePointer(cString),
@@ -45,12 +84,50 @@ extension String {
     self = result
   }
 
-  /// Create a new `String` by copying the nul-terminated data
-  /// referenced by a `cString` using `encoding`.
+  /// Creates a new string by copying the null-terminated data referenced by
+  /// the given pointer using the specified encoding.
+  ///
+  /// When you pass `true` as `isRepairing`, this method replaces ill-formed
+  /// sequences with the Unicode replacement character (`"\u{FFFD}"`);
+  /// otherwise, an ill-formed sequence causes this method to stop decoding
+  /// and return `nil`.
+  ///
+  /// The following example calls this method with pointers to the contents of
+  /// two different `CChar` arrays---the first with well-formed UTF-8 code
+  /// unit sequences and the second with an ill-formed sequence at the end.
+  ///
+  ///     let validUTF8: [UInt8] = [67, 97, 102, 195, 169, 0]
+  ///     validUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String.decodeCString(ptr.baseAddress,
+  ///                                      as: UTF8.self,
+  ///                                      repairingInvalidCodeUnits: true)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Optional((Café, false))"
+  ///
+  ///     let invalidUTF8: [UInt8] = [67, 97, 102, 195, 0]
+  ///     invalidUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String.decodeCString(ptr.baseAddress,
+  ///                                      as: UTF8.self,
+  ///                                      repairingInvalidCodeUnits: true)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Optional((Caf�, true))"
+  ///
+  /// - Parameters:
+  ///   - cString: A pointer to a null-terminated code sequence encoded in
+  ///     `encoding`.
+  ///   - encoding: The Unicode encoding of the data referenced by `cString`.
+  ///   - isRepairing: Pass `true` to create a new string, even when the data
+  ///     referenced by `cString` contains ill-formed sequences. Ill-formed
+  ///     sequences are replaced with the Unicode replacement character
+  ///     (`"\u{FFFD}"`). Pass `false` to interrupt the creation of the new
+  ///     string if an ill-formed sequence is detected.
+  /// - Returns: A tuple with the new string and a Boolean value that indicates
+  ///   whether any repairs were made. If `isRepairing` is `false` and an
+  ///   ill-formed sequence is detected, this method returns `nil`.
   ///
-  /// Returns `nil` if the `cString` is `nil` or if it contains ill-formed code
-  /// units and no repairing has been requested. Otherwise replaces
-  /// ill-formed code units with replacement characters (U+FFFD).
+  /// - SeeAlso: `UnicodeCodec`
   @warn_unused_result
   public static func decodeCString<Encoding : UnicodeCodec>(
     _ cString: UnsafePointer<Encoding.CodeUnit>?,

stdlib/public/core/Character.swift

@@ -10,9 +10,56 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// `Character` represents some Unicode grapheme cluster as
-/// defined by a canonical, localized, or otherwise tailored
-/// segmentation algorithm.
+/// A single extended grapheme cluster, which approximates a user-perceived
+/// character.
+///
+/// The `Character` type represents a character made up of one or more Unicode
+/// scalar values, grouped by a Unicode boundary algorithm. Generally, a
+/// `Character` instance matches what the reader of a string will perceive as
+/// a single character. The number of visible characters is generally the most
+/// natural way to count the length of a string.
+///
+///     let greeting = "Hello! 🐥"
+///     print("Character count: \(greeting.characters.count)")
+///     // Prints "Character count: 8"
+///
+/// Because each character in a string can be made up of one or more Unicode
+/// code points, the number of characters in a string may not match the length
+/// of the Unicode code point representation or the length of the string in a
+/// particular binary representation.
+///
+///     print("Unicode code point count: \(greeting.unicodeScalars.count)")
+///     // Prints "Unicode code point count: 15"
+///
+///     print("UTF-8 representation count: \(greeting.utf8.count)")
+///     // Prints "UTF-8 representation count: 18"
+///
+/// Every `Character` instance is composed of one or more Unicode code points
+/// that are grouped together as an *extended grapheme cluster*. The way these
+/// code points are grouped is defined by a canonical, localized, or otherwise
+/// tailored Unicode segmentation algorithm.
+///
+/// For example, a country's Unicode flag character is made up of two regional
+/// indicator code points that correspond to that country's ISO 3166-1 alpha-2
+/// code. The alpha-2 code for The United States is "US", so its flag
+/// character is made up of the Unicode code points `"\u{1F1FA}"` (REGIONAL
+/// INDICATOR SYMBOL LETTER U) and `"\u{1F1F8}"` (REGIONAL INDICATOR SYMBOL
+/// LETTER S). When placed next to each other in a Swift string literal, these
+/// two code points are combined into a single grapheme cluster, represented
+/// by a `Character` instance in Swift.
+///
+///     let usFlag: Character = "\u{1F1FA}\u{1F1F8}"
+///     print(usFlag)
+///     // Prints "🇺🇸"
+///
+/// For more information about the Unicode terms used in this discussion, see
+/// the [Unicode.org glossary][glossary]. In particular, this discussion
+/// mentions [extended grapheme clusters][clusters] and [Unicode scalar
+/// values][scalars].
+///
+/// [glossary]: http://www.unicode.org/glossary/
+/// [clusters]: http://www.unicode.org/glossary/#extended_grapheme_cluster
+/// [scalars]: http://www.unicode.org/glossary/#unicode_scalar_value
 public struct Character :
   _BuiltinExtendedGraphemeClusterLiteralConvertible,
   ExtendedGraphemeClusterLiteralConvertible, Equatable, Hashable, Comparable {
@@ -33,7 +80,9 @@ public struct Character :
     case small(Builtin.Int63)
   }
 
-  /// Construct a `Character` containing just the given `scalar`.
+  /// Creates a character containing the given Unicode scalar value.
+  ///
+  /// - Parameter scalar: The Unicode scalar value to convert into a character.
   public init(_ scalar: UnicodeScalar) {
     var asInt: UInt64 = 0
     var shift: UInt64 = 0
@@ -55,7 +104,17 @@ public struct Character :
         UTF32.self, input: CollectionOfOne(UInt32(value))))
   }
 
-  /// Create an instance initialized to `value`.
+  /// Creates a character with the specified value.
+  ///
+  /// Don't call this initializer directly. It is used by the compiler when you
+  /// use a string literal to initialize a `Character` instance. For example:
+  ///
+  ///     let snowflake: Character = "❄︎"
+  ///     print(snowflake)
+  ///     // Prints "❄︎"
+  ///
+  /// The assignment to the `snowflake` constant calls this initializer behind
+  /// the scenes.
   public init(unicodeScalarLiteral value: Character) {
     self = value
   }
@@ -73,14 +132,31 @@ public struct Character :
         isASCII: isASCII))
   }
 
-  /// Create an instance initialized to `value`.
+  /// Creates a character with the specified value.
+  ///
+  /// Don't call this initializer directly. It is used by the compiler when you
+  /// use a string literal to initialize a `Character` instance. For example:
+  ///
+  ///     let oBreve: Character = "o\u{306}"
+  ///     print(oBreve)
+  ///     // Prints "ŏ"
+  ///
+  /// The assignment to the `oBreve` constant calls this initializer behind the
+  /// scenes.
   public init(extendedGraphemeClusterLiteral value: Character) {
     self = value
   }
 
-  /// Create an instance from a single-character `String`.
+  /// Creates a character from a single-character string.
+  ///
+  /// The following example creates a new character from the uppercase version
+  /// of a string that only holds one character.
+  ///
+  ///     let a = "a"
+  ///     let capitalA = Character(a.uppercased())
   ///
-  /// - Precondition: `s` contains exactly one extended grapheme cluster.
+  /// - Parameter s: The single-character string to convert to a `Character`
+  ///   instance. `s` must contain exactly one extended grapheme cluster.
   public init(_ s: String) {
     // The small representation can accept up to 8 code units as long
     // as the last one is a continuation.  Since the high bit of the
@@ -260,13 +336,10 @@ public struct Character :
     var data: UInt64
   }
 
-  /// The hash value.
+  /// The character's hash value.
   ///
-  /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
-  ///
-  /// - Note: The hash value is not guaranteed to be stable across
-  ///   different invocations of the same program.  Do not persist the
-  ///   hash value across program runs.
+  /// Hash values are not guaranteed to be equal across different executions of
+  /// your program. Do not save hash values to use during a future execution.
   public var hashValue: Int {
     // FIXME(performance): constructing a temporary string is extremely
     // wasteful and inefficient.
@@ -283,14 +356,16 @@ public struct Character :
 }
 
 extension Character : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the character, suitable for debugging.
   public var debugDescription: String {
     return String(self).debugDescription
   }
 }
 
 extension String {
-  /// Construct an instance containing just the given `Character`.
+  /// Creates a string containing the given character.
+  ///
+  /// - Parameter c: The character to convert to a string.
   public init(_ c: Character) {
     switch c._representation {
     case let .small(_63bits):

stdlib/public/core/ClosedRange.swift

@@ -212,8 +212,8 @@ public struct CountableClosedRange<
     return ClosedRangeIndex(lowerBound)
   }
 
-  /// The range's "past the end" position, or one greater than the last valid
-  /// subscript argument.
+  /// The range's "past the end" position---that is, the position one greater
+  /// than the last valid subscript argument.
   public var endIndex: ClosedRangeIndex<Bound> {
     return ClosedRangeIndex()
   }

stdlib/public/core/Collection.swift

@@ -38,8 +38,8 @@ public protocol IndexableBase {
   /// If the collection is empty, `startIndex` is equal to `endIndex`.
   var startIndex: Index { get }
 
-  /// The collection's "past the end" position, or one greater than the last
-  /// valid subscript argument.
+  /// The collection's "past the end" position---that is, the position one
+  /// greater than the last valid subscript argument.
   ///
   /// When you need a range that includes the last element of a collection, use
   /// the half-open range operator (`..<`) with `endIndex`. The `..<` operator
@@ -158,8 +158,11 @@ public protocol IndexableBase {
 /// In most cases, it's best to ignore this protocol and use the `Collection`
 /// protocol instead, because it has a more complete interface.
 public protocol Indexable : IndexableBase {
-  /// A type that can represent the number of steps between a pair of
-  /// indices.
+  /// A type used to represent the number of steps between two indices, where
+  /// one value is reachable from the other.
+  ///
+  /// In Swift, *reachability* refers to the ability to produce one value from
+  /// the other through zero or more applications of `index(after:)`.
   associatedtype IndexDistance : SignedInteger = Int
 
   /// Returns an index that is the specified distance from the given index.

stdlib/public/core/CollectionOfOne.swift

@@ -50,10 +50,11 @@ public struct CollectionOfOne<Element>
     return 0
   }
 
-  /// The "past the end" position; always identical to
-  /// `index(after: startIndex)`.
+  /// The "past the end" position---that is, the position one greater than the
+  /// last valid subscript argument.
   ///
-  /// - Note: `endIndex` is not a valid argument to `subscript`.
+  /// In a `CollectionOfOne` instance, `endIndex` is always identical to
+  /// `index(after: startIndex)`.
   public var endIndex: Int {
     return 1
   }