[cxx-interop] NFC: Clarify copying semantics

Author: egorzhdan

stdlib/public/Cxx/CxxConvertibleToCollection.swift

@@ -40,11 +40,12 @@ internal func forEachElement<C: CxxConvertibleToCollection>(
 extension Array {
   /// Creates an array containing the elements of a C++ container.
   ///
-  /// This initializer copies each element of the C++ container to a new Swift
-  /// array.
+  /// This initializes the array by copying every element of the C++ container.
   ///
   /// - Complexity: O(*n*), where *n* is the number of elements in the C++
-  ///   container.
+  ///   container when each element is copied in O(1). Note that this might not
+  ///   be true for certain C++ types, e.g. those with a custom copy
+  ///   constructor that performs additional logic.
   public init<C: CxxConvertibleToCollection>(_ c: C)
     where C.RawIterator.Pointee == Element {
 
@@ -56,11 +57,12 @@ extension Array {
 extension Set {
   /// Creates an set containing the elements of a C++ container.
   ///
-  /// This initializer copies each element of the C++ container to a new Swift
-  /// set.
+  /// This initializes the set by copying every element of the C++ container.
   ///
   /// - Complexity: O(*n*), where *n* is the number of elements in the C++
-  ///   container.
+  ///   container when each element is copied in O(1). Note that this might not
+  ///   be true for certain C++ types, e.g. those with a custom copy
+  ///   constructor that performs additional logic.
   public init<C: CxxConvertibleToCollection>(_ c: C)
     where C.RawIterator.Pointee == Element {
 

stdlib/public/Cxx/CxxSequence.swift

@@ -126,7 +126,9 @@ extension CxxSequence {
   /// Returns an iterator over the elements of this C++ container.
   ///
   /// - Complexity: O(*n*), where *n* is the number of elements in the C++
-  ///   container.
+  ///   container when each element is copied in O(1). Note that this might not
+  ///   be true for certain C++ types, e.g. those with a custom copy
+  ///   constructor that performs additional logic.
   @inlinable
   public func makeIterator() -> CxxIterator<Self> {
     return CxxIterator(sequence: self)