Merge pull request #67309 from apple/egorzhdan/5.9-doc-overlay-protocols

🍒[cxx-interop] NFC: Add doc comments for overlay protocols

Author: egorzhdan

stdlib/public/Cxx/CxxDictionary.swift

@@ -10,6 +10,10 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A C++ type that represents a dictionary.
+///
+/// C++ standard library types such as `std::map` and `std::unordered_map`
+/// conform to this protocol.
 public protocol CxxDictionary<Key, Value> {
   associatedtype Key
   associatedtype Value

stdlib/public/Cxx/CxxPair.swift

@@ -10,6 +10,9 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A C++ type that represents a pair of two values.
+///
+/// C++ standard library type `std::pair` conforms to this protocol.
 public protocol CxxPair<First, Second> {
   associatedtype First
   associatedtype Second

stdlib/public/Cxx/CxxSet.swift

@@ -10,6 +10,12 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A C++ type that represents a set of values, which might be repeating.
+///
+/// C++ standard library types such as `std::set`, `std::unordered_set` and
+/// `std::multiset` conform to this protocol.
+///
+/// - SeeAlso: `CxxUniqueSet`
 public protocol CxxSet<Element> {
   associatedtype Element
   associatedtype Size: BinaryInteger
@@ -41,12 +47,18 @@ extension CxxSet {
     }
   }
 
+  /// Returns a Boolean value that indicates whether the given element exists
+  /// in the set.
   @inlinable
   public func contains(_ element: Element) -> Bool {
     return count(element) > 0
   }
 }
 
+/// A C++ type that represents a set of unique values.
+///
+/// C++ standard library types such as `std::set` and `std::unordered_set`
+/// conform to this protocol.
 public protocol CxxUniqueSet<Element>: CxxSet {
   override associatedtype Element
   override associatedtype Size: BinaryInteger
@@ -57,12 +69,22 @@ public protocol CxxUniqueSet<Element>: CxxSet {
 }
 
 extension CxxUniqueSet {
+  /// Inserts the given element in the set if it is not already present.
+  ///
+  /// If an element equal to `newMember` is already contained in the set, this
+  /// method has no effect.
+  ///
+  /// - Parameter newMember: An element to insert into the set.
+  /// - Returns: `(true, newMember)` if `newMember` was not contained in the
+  ///   set. If an element equal to `newMember` was already contained in the
+  ///   set, the method returns `(false, oldMember)`, where `oldMember` is the
+  ///   element that was equal to `newMember`.
   @inlinable
   @discardableResult
   public mutating func insert(
-    _ element: Element
+    _ newMember: Element
   ) -> (inserted: Bool, memberAfterInsert: Element) {
-    let insertionResult = self.__insertUnsafe(element)
+    let insertionResult = self.__insertUnsafe(newMember)
     let rawIterator: RawMutableIterator = insertionResult.first
     let inserted: Bool = insertionResult.second
     return (inserted, rawIterator.pointee)