[stdlib] Updated underestimatedCount doc related to complexity

There were inconsistencies in the documentation about the complexity of the underestimatedCount property.

Author: Thomas Di Meco

stdlib/public/core/LazyCollection.swift

@@ -84,10 +84,11 @@ extension LazyCollection : Sequence {
     return _base.makeIterator()
   }
 
-  /// Returns a value less than or equal to the number of elements in
-  /// `self`, **nondestructively**.
+  /// A value less than or equal to the number of elements in the collection.
   ///
-  /// - Complexity: O(*n*)
+  /// - Complexity: O(1) if the collection conforms to
+  ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
+  ///   of the collection.
   @_inlineable
   public var underestimatedCount: Int { return _base.underestimatedCount }
 

stdlib/public/core/Map.swift

@@ -80,10 +80,14 @@ extension LazyMapSequence: LazySequenceProtocol {
     return Iterator(_base: _base.makeIterator(), _transform: _transform)
   }
 
-  /// Returns a value less than or equal to the number of elements in
-  /// `self`, **nondestructively**.
+  /// A value less than or equal to the number of elements in the sequence,
+  /// calculated nondestructively.
   ///
-  /// - Complexity: O(*n*)
+  /// The default implementation returns 0. If you provide your own
+  /// implementation, make sure to compute the value nondestructively.
+  ///
+  /// - Complexity: O(1), except if the sequence also conforms to `Collection`.
+  ///   In this case, see the documentation of `Collection.underestimatedCount`.
   @_inlineable
   public var underestimatedCount: Int {
     return _base.underestimatedCount
@@ -122,6 +126,11 @@ extension LazyMapCollection: Sequence {
     return Iterator(_base: _base.makeIterator(), _transform: _transform)
   }
 
+  /// A value less than or equal to the number of elements in the collection.
+  ///
+  /// - Complexity: O(1) if the collection conforms to
+  ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
+  ///   of the collection.
   @_inlineable
   public var underestimatedCount: Int {
     return _base.underestimatedCount
@@ -204,6 +213,11 @@ extension LazyMapCollection: LazyCollectionProtocol {
 extension LazyMapCollection : BidirectionalCollection
   where Base : BidirectionalCollection {
 
+  /// A value less than or equal to the number of elements in the collection.
+  ///
+  /// - Complexity: O(1) if the collection conforms to
+  ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
+  ///   of the collection.
   @_inlineable
   public func index(before i: Index) -> Index { return _base.index(before: i) }
 

stdlib/public/core/Sequence.swift

@@ -338,10 +338,14 @@ public protocol Sequence {
   /// Returns an iterator over the elements of this sequence.
   func makeIterator() -> Iterator
 
-  /// A value less than or equal to the number of elements in
-  /// the sequence, calculated nondestructively.
+  /// A value less than or equal to the number of elements in the sequence,
+  /// calculated nondestructively.
   ///
-  /// - Complexity: O(1)
+  /// The default implementation returns 0. If you provide your own
+  /// implementation, make sure to compute the value nondestructively.
+  ///
+  /// - Complexity: O(1), except if the sequence also conforms to `Collection`.
+  ///   In this case, see the documentation of `Collection.underestimatedCount`.
   var underestimatedCount: Int { get }
 
   /// Returns an array containing the results of mapping the given closure
@@ -885,10 +889,14 @@ extension Sequence {
     return Array(result)
   }
 
-  /// Returns a value less than or equal to the number of elements in
-  /// the sequence, nondestructively.
+  /// A value less than or equal to the number of elements in the sequence,
+  /// calculated nondestructively.
+  ///
+  /// The default implementation returns 0. If you provide your own
+  /// implementation, make sure to compute the value nondestructively.
   ///
-  /// - Complexity: O(*n*)
+  /// - Complexity: O(1), except if the sequence also conforms to `Collection`.
+  ///   In this case, see the documentation of `Collection.underestimatedCount`.
   @_inlineable
   public var underestimatedCount: Int {
     return 0