Correct Chunked documentation (#182)

* Clarify that the determining factor for being grouped is equality (`Equatable`), which doesn’t necessarily mean the _same_ value (identity)
* Correct algorithmic complexity documentation on the lazy Chunked functions
* Document `belongInSameGroup` and `projection`

Author: mdznr

Guides/Chunked.md

@@ -112,7 +112,8 @@ collection is bidirectional. `ChunksOfCountCollection` and
 
 ### Complexity
 
-The eager methods are O(_n_), the lazy methods are O(_1_).
+The eager methods are O(_n_) where _n_ is the number of elements in the
+collection. The lazy methods are O(_n_) because the start index is pre-computed.
 
 ### Naming
 

Sources/Algorithms/Chunked.swift

@@ -410,6 +410,9 @@ extension LazySequenceProtocol where Self: Collection, Elements: Collection {
   /// Returns a lazy collection of subsequences of this collection, chunked by
   /// the given predicate.
   ///
+  /// - Parameter belongInSameGroup: A closure that takes two adjacent elements
+  /// of the sequence and returns whether or not they belong in the same group.
+  ///
   /// - Complexity: O(*n*), because the start index is pre-computed.
   @inlinable
   public func chunked(
@@ -422,7 +425,11 @@ extension LazySequenceProtocol where Self: Collection, Elements: Collection {
   }
 
   /// Returns a lazy collection of subsequences of this collection, chunked by
-  /// grouping elements that project to the same value.
+  /// grouping elements that project to equal values.
+  ///
+  /// - Parameter projection: A closure that takes an element in the sequence
+  /// and returns an `Equatable` value that can be used to determine if adjacent
+  /// elements belong in the same group.
   ///
   /// - Complexity: O(*n*), because the start index is pre-computed.
   @inlinable
@@ -443,6 +450,10 @@ extension Collection {
   /// Returns a collection of subsequences of this collection, chunked by the
   /// given predicate.
   ///
+  /// - Parameter belongInSameGroup: A closure that takes two adjacent elements
+  /// of the collection and returns whether or not they belong in the same
+  /// group.
+  ///
   /// - Complexity: O(*n*), where *n* is the length of this collection.
   @inlinable
   public func chunked(
@@ -470,7 +481,11 @@ extension Collection {
   }
 
   /// Returns a collection of subsequences of this collection, chunked by
-  /// grouping elements that project to the same value.
+  /// grouping elements that project to equal values.
+  ///
+  /// - Parameter projection: A closure that takes an element in the collection
+  /// and returns an `Equatable` value that can be used to determine if adjacent
+  /// elements belong in the same group.
   ///
   /// - Complexity: O(*n*), where *n* is the length of this collection.
   @inlinable