[stdlib] Various minor documentation edits (#3614)

* [stdlib] Fix UTF8View example code
* [stdlib] Update code sample for SE-0099
* [stdlib] Standardize operator naming
* [stdlib] Minor edits to Error documentation

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -229,7 +229,7 @@ if True:
 /// array's first and last elements. If the array is empty, these properties
 /// are `nil`.
 ///
-///     if let firstElement = oddNumbers.first, lastElement = oddNumbers.last {
+///     if let firstElement = oddNumbers.first, let lastElement = oddNumbers.last {
 ///         print(firstElement, lastElement, separator: ", ")
 ///     }
 ///     // Prints "1, 15"

stdlib/public/core/Comparable.swift

@@ -48,7 +48,7 @@
 /// =====================================
 ///
 /// Types with Comparable conformance implement the less-than operator (`<`)
-/// and the is-equal-to operator (`==`). These two operations impose a strict
+/// and the equal-to operator (`==`). These two operations impose a strict
 /// total order on the values of a type, in which exactly one of the following
 /// must be true for any two values `a` and `b`:
 ///

stdlib/public/core/Equatable.swift

@@ -17,9 +17,9 @@
 /// A type that can be compared for value equality.
 ///
 /// Types that conform to the `Equatable` protocol can be compared for equality
-/// using the is-equal-to operator (`==`) or inequality using the
-/// is-not-equal-to operator (`!=`). Most basic types in the Swift standard
-/// library conform to `Equatable`.
+/// using the equal-to operator (`==`) or inequality using the not-equal-to
+/// operator (`!=`). Most basic types in the Swift standard library conform to
+/// `Equatable`.
 ///
 /// Some sequence and collection operations can be used more simply when the
 /// elements conform to `Equatable`. For example, to check whether an array
@@ -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 "is equal to" operator
-/// (`==`). The standard library provides an implementation for the "is 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 (`==`).
+/// 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
@@ -136,9 +136,9 @@
 ///         return lhs.value == rhs.value
 ///     }
 ///
-/// The implementation of the `==` function returns the same value whether
-/// its two arguments are the same instance or are two different instances
-/// with the same integer stored in their `value` properties. For example:
+/// The implementation of the `==` function returns the same value whether its
+/// two arguments are the same instance or are two different instances with
+/// the same integer stored in their `value` properties. For example:
 ///
 ///     let a = IntegerRef(100)
 ///     let b = IntegerRef(100)
@@ -147,7 +147,7 @@
 ///     // Prints "true, true"
 ///
 /// Class instance identity, on the other hand, is compared using the
-/// triple-equals "is identical to" operator (`===`). For example:
+/// triple-equals identical-to operator (`===`). For example:
 ///
 ///     let c = a
 ///     print(a === c, b === c, separator: ", ")
@@ -169,7 +169,7 @@ public protocol Equatable {
 /// Inequality is the inverse of equality. For any values `a` and `b`, `a != b`
 /// implies that `a == b` is `false`.
 ///
-/// This is the default implementation of the is-not-equal-to operator (`!=`)
+/// This is the default implementation of the not-equal-to operator (`!=`)
 /// for any type that conforms to `Equatable`.
 ///
 /// - Parameters:

stdlib/public/core/ErrorType.swift

@@ -14,18 +14,19 @@ import SwiftShims
 // TODO: API review
 /// A type representing an error value that can be thrown.
 ///
-/// Any type that declares conformance to `Error` can be used to
-/// represent an error in Swift's error handling system. Because
-/// `Error` has no requirements of its own, you can declare
-/// conformance on any custom type you create.
+/// Any type that declares conformance to the `Error` protocol can be used to
+/// represent an error in Swift's error handling system. Because the `Error`
+/// protocol has no requirements of its own, you can declare conformance on
+/// any custom type you create.
 ///
 /// Using Enumerations as Errors
 /// ============================
 ///
 /// Swift's enumerations are well suited to represent simple errors. Create an
-/// enumeration that conforms to `Error` with a case for each possible
-/// error. If there are additional details about the error that could be
-/// helpful for recovery, use associated values to include that information.
+/// enumeration that conforms to the `Error` protocol with a case for each
+/// possible error. If there are additional details about the error that could
+/// be helpful for recovery, use associated values to include that
+/// information.
 ///
 /// The following example shows an `IntParsingError` enumeration that captures
 /// two different kinds of errors that can occur when parsing an integer from

stdlib/public/core/Hashable.swift

@@ -37,7 +37,7 @@
 /// To use your own custom type in a set or as the key type of a dictionary,
 /// add `Hashable` conformance to your type by providing a `hashValue`
 /// property. The `Hashable` protocol inherits from the `Equatable` protocol,
-/// so you must also add an is-equal-to operator (`==`) function for your
+/// so you must also add an equal-to operator (`==`) function for your
 /// custom type.
 ///
 /// As an example, consider a `GridPoint` type that describes a location in a

stdlib/public/core/String.swift

@@ -60,7 +60,7 @@ import SwiftShims
 ///     print(greeting)
 ///     // Prints "Welcome!"
 ///
-/// Comparing strings for equality using the is-equal-to operator (`==`) or a
+/// Comparing strings for equality using the equal-to operator (`==`) or a
 /// relational operator (like `<` and `>=`) is always performed using the
 /// Unicode canonical representation. This means that different
 /// representations of a string compare as being equal.

stdlib/public/core/StringUTF8.swift

@@ -154,15 +154,15 @@ extension String {
   ///
   ///     print(strncmp(s1, s2, 14))
   ///     // Prints "0"
-  ///     print(String(s1.utf8.prefix(14))
+  ///     print(String(s1.utf8.prefix(14)))
   ///     // Prints "They call me '"
   ///
   /// Extending the compared character count to 15 includes the differing
   /// characters, so a nonzero result is returned.
   ///
   ///     print(strncmp(s1, s2, 15))
   ///     // Prints "-17"
-  ///     print(String(s1.utf8.prefix(14))
+  ///     print(String(s1.utf8.prefix(15)))
   ///     // Prints "They call me 'B"
   public struct UTF8View
     : Collection,