[Stdlib] Add notes to lazy collection doc comments about complexity

Many lazy collections don't offer O(1) performance for `startIndex`,
`first`, or any method that depends on `startIndex`.
`LazyFilterCollection` already had a note to this effect (which I
tweaked a bit), but `FlattenCollection` didn't.

Related to SR-425.

Author: lilyball

stdlib/public/core/Filter.swift

@@ -148,12 +148,12 @@ public func == <Base : CollectionType>(
 /// A lazy `CollectionType` wrapper that includes the elements of an
 /// underlying collection that satisfy a predicate.
 ///
-/// - Note: The performance of advancing a `LazyFilterIndex`
-///   depends on how sparsely the filtering predicate is satisfied,
-///   and may not offer the usual performance given by models of
-///   `ForwardIndexType`.  Be aware, therefore, that general operations
-///   on `LazyFilterCollection` instances may not have the
-///   documented complexity.
+/// - Note: The performance of accessing `startIndex`, `first`, any methods
+///   that depend on `startIndex`, or of advancing a `LazyFilterIndex` depends
+///   on how sparsely the filtering predicate is satisfied, and may not offer
+///   the usual performance given by `CollectionType` or `ForwardIndexType`. Be
+///   aware, therefore, that general operations on `LazyFilterCollection`
+///   instances may not have the documented complexity.
 public struct LazyFilterCollection<
   Base : CollectionType
 > : LazyCollectionType {

stdlib/public/core/Flatten.swift.gyb

@@ -225,6 +225,14 @@ public func == <BaseElements> (
 /// * `c.flatten().map(f)` maps eagerly and returns a new array
 /// * `c.lazy.flatten().map(f)` maps lazily and returns a `LazyMapCollection`
 ///
+/// - Note: The performance of accessing `startIndex`, `first`, any methods
+///   that depend on `startIndex`, or of advancing a `${Collection}Index`
+///   depends on how many empty subcollections are found in the base
+///   collection, and may not offer the usual performance given by
+///   `CollectionType` or `${traversal}IndexType`. Be aware, therefore, that
+///   general operations on `${Collection}` instances may not have the
+///   documented complexity.
+///
 /// - See also: `FlattenSequence`
 public struct ${Collection}<
   Base: CollectionType where ${constraints % {'Base': 'Base.'}}