[stdlib] Revisions to dictionaries and 'Policy' protocols

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

stdlib/public/core/CompilerProtocols.swift

@@ -190,13 +190,11 @@ 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
@@ -204,13 +202,11 @@ public func == <
   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)...)