[stdlib] Revisions to dictionaries and 'Policy' protocols

This revises documentation for Dictionary and the related types and protocols,
including Equatable, Comparable, and Hashable.

Author: natecook1000

stdlib/public/core/CompilerProtocols.swift

@@ -190,27 +190,23 @@ public protocol RawRepresentable {
   var rawValue: RawValue { get }
 }
 
-/// Returns a Boolean value indicating whether the two operands are equal.
+/// Returns a Boolean value indicating whether the two arguments are equal.
 ///
 /// - Parameters:
 ///   - lhs: A raw-representable instance.
 ///   - rhs: A second raw-representable instance.
-/// - Returns: `true` if the two operands have equal raw values; otherwise,
-///   `false`.
 @warn_unused_result
 public func == <
   T : RawRepresentable where T.RawValue : Equatable
 >(lhs: T, rhs: T) -> Bool {
   return lhs.rawValue == rhs.rawValue
 }
 
-/// Returns a Boolean value indicating whether the two operands are not equal.
+/// Returns a Boolean value indicating whether the two arguments are not equal.
 ///
 /// - Parameters:
 ///   - lhs: A raw-representable instance.
 ///   - rhs: A second raw-representable instance.
-/// - Returns: `true` if the two operands have unequal raw values; otherwise,
-///   `false`.
 @warn_unused_result
 public func != <
   T : RawRepresentable where T.RawValue : Equatable
@@ -220,13 +216,11 @@ public func != <
 
 // This overload is needed for ambiguity resolution against the
 // implementation of != for T : Equatable
-/// Returns a Boolean value indicating whether the two operands are not equal.
+/// Returns a Boolean value indicating whether the two arguments are not equal.
 ///
 /// - Parameters:
 ///   - lhs: A raw-representable instance.
 ///   - rhs: A second raw-representable instance.
-/// - Returns: `true` if the two operands have unequal raw values; otherwise,
-///   `false`.
 @warn_unused_result
 public func != <
   T : Equatable where T : RawRepresentable, T.RawValue : Equatable
@@ -478,9 +472,69 @@ public protocol ArrayLiteralConvertible {
   init(arrayLiteral elements: Element...)
 }
 
-/// Conforming types can be initialized with dictionary literals.
+/// A type that can be initialized using a dictionary literal.
+///
+/// A dictionary literal is a simple way of writing a list of key-value pairs.
+/// You write each key-value pair with a colon (`:`) separating the key and
+/// the value. The dictionary literal is made up of one or more key-value
+/// pairs, separated by commas and surrounded with square brackets.
+///
+/// To declare a dictionary, assign a dictionary literal to a variable or
+/// constant:
+///
+///     let countryCodes = ["BR": "Brazil", "GH": "Ghana",
+///                         "JP": "Japan", "US": "United States"]
+///     // 'countryCodes' has type [String: String]
+///
+///     print(countryCodes["BR"]!)
+///     // Prints "Brazil"
+///
+/// When the context provides enough type information, you can use a special
+/// form of the dictionary literal, square brackets surrounding a single
+/// colon, to initialize an empty dictionary.
+///
+///     var frequencies: [String: Int] = [:]
+///     print(frequencies.count)
+///     // Prints "0"
+///
+/// - Note: A dictionary literal is *not* the same as an instance of
+///   `Dictionary` or the similarly named `DictionaryLiteral` type. You can't
+///   initialize a type that conforms to `DictionaryLiteralConvertible` simply
+///   by assigning an instance of one of these types.
+///
+/// Conforming to the DictionaryLiteralConvertible Protocol
+/// =======================================================
+///
+/// To add the capability to be initialized with a dictionary literal to your
+/// own custom types, declare an `init(dictionaryLiteral:)` initializer. The
+/// following example shows the dictionary literal initializer for a
+/// hypothetical `CountedSet` type, which uses setlike semantics while keeping
+/// track of the count for duplicate elements:
+///
+///     struct CountedSet<Element: Hashable>: Collection, SetAlgebra {
+///         // implementation details
+///
+///         /// Updates the count stored in the set for the given element,
+///         /// adding the element if necessary.
+///         ///
+///         /// - Parameter n: The new count for `element`. `n` must be greater
+///         ///   than or equal to zero.
+///         /// - Parameter element: The element to set the new count on.
+///         mutating func updateCount(_ n: Int, for element: Element)
+///     }
+///
+///     extension CountedSet: DictionaryLiteralConvertible {
+///         init(dictionaryLiteral elements: (Element, Int)...) {
+///             self.init()
+///             for (element, count) in elements {
+///                 self.updateCount(count, for: element)
+///             }
+///         }
+///     }
 public protocol DictionaryLiteralConvertible {
+  /// The key type of a dictionary literal.
   associatedtype Key
+  /// The value type of a dictionary literal.
   associatedtype Value
   /// Create an instance initialized with `elements`.
   init(dictionaryLiteral elements: (Key, Value)...)

stdlib/public/core/FixedPoint.swift.gyb

@@ -546,16 +546,27 @@ public func ${op}(lhs: ${Self}, rhs: ${Self}) -> ${Self} {
 %end
 
 // Bitwise negate
+/// Returns the inverse of the bits set in the argument.
+///
+/// - SeeAlso: `BitwiseOperations`
 @_transparent
 public prefix func ~(rhs: ${Self}) -> ${Self} {
   let mask = ${Self}.subtractWithOverflow(0, 1).0
   return ${Self}(Builtin.xor_${BuiltinName}(rhs._value, mask._value))
 }
 
-% for op, name in (
-%  ('==','eq'), ('!=','ne'),
-%  ('<', sign + 'lt'), ('<=', sign + 'le'),
-%  ('>', sign + 'gt'), ('>=', sign + 'ge')):
+% for op, name, comment in (
+%   ('==', 'eq', 'the two arguments have equal values'),
+%   ('!=', 'ne', 'the two arguments have unequal values'),
+%   ('<', sign + 'lt', 'the first argument is less than the second argument'),
+%   ('<=', sign + 'le', 'the first argument is less than or equal to the second argument'),
+%   ('>', sign + 'gt', 'the first argument is greater than the second argument'),
+%   ('>=', sign + 'ge', 'the first argument is greater than or equal to the second argument'),
+% ):
+/// Returns a Boolean value that indicates whether
+/// ${comment}.
+///
+/// - SeeAlso: `Equatable`, `Comparable`
 @_transparent
 public func ${op} (lhs: ${Self}, rhs: ${Self}) -> Bool {
   return Bool(Builtin.cmp_${name}_${BuiltinName}(lhs._value, rhs._value))
@@ -576,22 +587,38 @@ public func ${op} (lhs: ${Self}, rhs: ${Self}) -> ${Self} {
 }
 % end
 
-% for op, name in (('&','and'), ('^','xor'), ('|','or')):
+% for op, name, comment in (
+%   ('&', 'and', 'intersection of bits set in'),
+%   ('^', 'xor', 'bits that are set in exactly one of'),
+%   ('|', 'or', 'union of bits set in'),
+% ):
+/// Returns the ${comment} the two arguments.
+///
+/// - SeeAlso: `BitwiseOperations`
 @_transparent
 public func ${op} (lhs: ${Self}, rhs: ${Self}) -> ${Self} {
   return ${Self}(Builtin.${name}_${BuiltinName}(lhs._value, rhs._value))
 }
+
+/// Calculates the ${comment} the two arguments
+/// and stores the result in the first argument.
+///
+/// - SeeAlso: `BitwiseOperations`
+@_transparent
+public func ${op}=(lhs: inout ${Self}, rhs: ${Self}) {
+  lhs = lhs ${op} rhs
+}
 % end
 
 // Bitwise operations
 @_transparent
 extension ${Self} : BitwiseOperations {
-  /// The empty bitset of type ${Self}.
+  /// The empty bitset of type `${Self}`.
   public static var allZeros: ${Self} { return 0 }
 }
 
 // Compound assignments
-% for op in '+', '-', '*', '<<', '>>', '&', '|', '^':
+% for op in '+', '-', '*', '<<', '>>':
 @_transparent
 public func ${op}=(lhs: inout ${Self}, rhs: ${Self}) {
   lhs = lhs ${op} rhs