Merge pull request swiftlang#36709 from amartini51/main

Doc comment corrections

Author: amartini51

stdlib/public/Darwin/Foundation/NSStringAPI.swift

@@ -1669,7 +1669,7 @@ extension StringProtocol where Index == String.Index {
   // forward trivially to rangeOfString.
 
   /// Returns `true` if `other` is non-empty and contained within `self` by
-  /// case-sensitive, non-literal search. Otherwise, returns `false`.
+  /// case-sensitive, non-literal search; otherwise, returns `false`.
   ///
   /// Equivalent to `self.range(of: other) != nil`
   public func contains<T : StringProtocol>(_ other: T) -> Bool {

stdlib/public/core/Dictionary.swift

@@ -831,9 +831,8 @@ extension Dictionary: ExpressibleByDictionaryLiteral {
 }
 
 extension Dictionary {
-  /// Accesses the value with the given key. If the dictionary doesn't contain
-  /// the given key, accesses the provided default value as if the key and
-  /// default value existed in the dictionary.
+  /// Accesses the value with the given key, falling back to the given default
+  /// value if the key isn't found.
   ///
   /// Use this subscript when you want either the value for a particular key
   /// or, when that key is not present in the dictionary, a default value. This
@@ -866,7 +865,7 @@ extension Dictionary {
   ///     }
   ///     // letterCounts == ["H": 1, "e": 2, "l": 4, "o": 1, ...]
   ///
-  /// When `letterCounts[letter, defaultValue: 0] += 1` is executed with a
+  /// When `letterCounts[letter, default: 0] += 1` is executed with a
   /// value of `letter` that isn't already a key in `letterCounts`, the
   /// specified default value (`0`) is returned from the subscript,
   /// incremented, and then added to the dictionary under that key.

stdlib/public/core/FloatingPoint.swift

@@ -416,7 +416,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable
   ///     let x = -33.375
   ///     // x.sign == .minus
   ///
-  /// Do not use this property to check whether a floating point value is
+  /// Don't use this property to check whether a floating point value is
   /// negative. For a value `x`, the comparison `x.sign == .minus` is not
   /// necessarily the same as `x < 0`. In particular, `x.sign == .minus` if
   /// `x` is -0, and while `x < 0` is always `false` if `x` is NaN, `x.sign`
@@ -1130,7 +1130,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable
   /// A Boolean value indicating whether this instance is finite.
   ///
   /// All values other than NaN and infinity are considered finite, whether
-  /// normal or subnormal.
+  /// normal or subnormal.  For NaN, both `isFinite` and `isInfinite` are false.
   var isFinite: Bool { get }
 
   /// A Boolean value indicating whether the instance is equal to zero.
@@ -1147,7 +1147,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable
   /// A Boolean value indicating whether the instance is subnormal.
   ///
   /// A *subnormal* value is a nonzero number that has a lesser magnitude than
-  /// the smallest normal number. Subnormal values do not use the full
+  /// the smallest normal number. Subnormal values don't use the full
   /// precision available to values of a type.
   ///
   /// Zero is neither a normal nor a subnormal number. Subnormal numbers are
@@ -1157,8 +1157,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable
 
   /// A Boolean value indicating whether the instance is infinite.
   ///
-  /// Note that `isFinite` and `isInfinite` do not form a dichotomy, because
-  /// they are not total: If `x` is `NaN`, then both properties are `false`.
+  /// For NaN, both `isFinite` and `isInfinite` are false.
   var isInfinite: Bool { get }
 
   /// A Boolean value indicating whether the instance is NaN ("not a number").

stdlib/public/core/FloatingPointTypes.swift.gyb

@@ -92,6 +92,12 @@ public struct ${Self} {
 ${Availability(bits)}
 extension ${Self}: CustomStringConvertible {
   /// A textual representation of the value.
+  ///
+  /// For any finite value, this property provides a string that can be
+  /// converted back to an instance of `${Self}` without rounding errors.  That
+  /// is, if `x` is an instance of `${Self}`, then `${Self}(x.description) ==
+  /// x` is always true.  For any NaN value, the property's value is "nan", and
+  /// for positive and negative infinity its value is "inf" and "-inf".
   public var description: String {
     if isNaN {
       return "nan"
@@ -108,6 +114,9 @@ extension ${Self}: CustomStringConvertible {
 ${Availability(bits)}
 extension ${Self}: CustomDebugStringConvertible {
   /// A textual representation of the value, suitable for debugging.
+  ///
+  /// This property has the same value as the `description` property, except
+  /// that NaN values are printed in an extended format.
   public var debugDescription: String {
     var (buffer, length) = _float${bits}ToString(self, debug: true)
     return buffer.withBytes { (bufferPtr) in

stdlib/public/core/Integers.swift

@@ -58,9 +58,7 @@ extension ExpressibleByIntegerLiteral
 /// =============================================
 ///
 /// To add `AdditiveArithmetic` protocol conformance to your own custom type,
-/// implement the required operators, and provide a static `zero` property
-/// using a type that can represent the magnitude of any value of your custom
-/// type.
+/// implement the required operators, and provide a static `zero` property.
 public protocol AdditiveArithmetic: Equatable {
   /// The zero value.
   ///

stdlib/public/core/KeyPath.swift

@@ -30,10 +30,10 @@ internal func _abstract(
 // The two must coexist, so it was renamed. The old name must not be
 // used in the new runtime. _TtCs11_AnyKeyPath is the mangled name for
 // Swift._AnyKeyPath.
-@_objcRuntimeName(_TtCs11_AnyKeyPath)
 
 /// A type-erased key path, from any root type to any resulting value
 /// type.
+@_objcRuntimeName(_TtCs11_AnyKeyPath)
 public class AnyKeyPath: Hashable, _AppendKeyPath {
   /// The root type for this key path.
   @inlinable

stdlib/public/core/ManagedBuffer.swift

@@ -376,7 +376,7 @@ extension ManagedBufferPointer {
   }
 
   /// Returns `true` if `self` holds the only strong reference to its
-  /// buffer. Otherwise, returns `false`.
+  /// buffer; otherwise, returns `false`.
   ///
   /// See `isKnownUniquelyReferenced` for details.
   @inlinable

stdlib/public/core/SIMDVector.swift

@@ -815,7 +815,7 @@ extension SIMD where Scalar: FixedWidthInteger {
   /// Returns the sum of the scalars in the vector, computed with wrapping
   /// addition.
   ///
-  /// Equivalent to indices.reduce(into: 0) { $0 &+= self[$1] }.
+  /// Equivalent to `indices.reduce(into: 0) { $0 &+= self[$1] }`.
   @_alwaysEmitIntoClient
   public func wrappedSum() -> Scalar {
     return indices.reduce(into: 0) { $0 &+= self[$1] }