Tweak docs for split extensions (#256)

- Fix the doc for `splitAfter` to use "after" instead of "before".
- Expand the details for the "after" methods with a more explicit
  mention of how the element that satisfies the predicate is the last
  value in it's sublist.
- Use the same input for the example in `splitBefore` as `splitAFter` so
  that the distinction is more clear.
- Use "remaining elements" instead of "final elements".

Author: natebosch

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 1.17.1-dev
 
 * Require Dart 2.18
+* Improve docs for `splitAfter` and `splitBefore`.
 
 ## 1.17.0
 

lib/src/iterable_extensions.dart

@@ -415,27 +415,28 @@ extension IterableExtension<T> on Iterable<T> {
   /// Splits the elements into chunks before some elements.
   ///
   /// Each element except the first is checked using [test]
-  /// for whether it should start a new chunk.
+  /// for whether it should be the first element in a new chunk.
   /// If so, the elements since the previous chunk-starting element
   /// are emitted as a list.
-  /// Any final elements are emitted at the end.
+  /// Any remaining elements are emitted at the end.
   ///
   /// Example:
   /// Example:
   /// ```dart
-  /// var parts = [1, 2, 3, 4, 5, 6, 7, 8, 9].split(isPrime);
-  /// print(parts); // ([1], [2], [3, 4], [5, 6], [7, 8, 9])
+  /// var parts = [1, 0, 2, 1, 5, 7, 6, 8, 9].splitBefore(isPrime);
+  /// print(parts); // ([1, 0], [2, 1], [5], [7, 6, 8, 9])
   /// ```
   Iterable<List<T>> splitBefore(bool Function(T element) test) =>
       splitBeforeIndexed((_, element) => test(element));
 
-  /// Splits the elements into chunks before some elements.
+  /// Splits the elements into chunks after some elements.
   ///
-  /// Each element is checked using [test] for whether it should start a new
-  /// chunk.
-  /// If so, the elements since the previous chunk-starting element
+  /// Each element is checked using [test] for whether it should end a chunk.
+  /// If so, the elements following the previous chunk-ending element,
+  /// including the element that satisfied [test],
   /// are emitted as a list.
-  /// Any final elements are emitted at the end.
+  /// Any remaining elements are emitted at the end,
+  /// whether the last element should be split after or not.
   ///
   /// Example:
   /// ```dart
@@ -451,7 +452,7 @@ extension IterableExtension<T> on Iterable<T> {
   /// for whether a chunk should end between them.
   /// If so, the elements since the previous chunk-splitting elements
   /// are emitted as a list.
-  /// Any final elements are emitted at the end.
+  /// Any remaining elements are emitted at the end.
   ///
   /// Example:
   /// ```dart
@@ -467,7 +468,7 @@ extension IterableExtension<T> on Iterable<T> {
   /// for whether it should start a new chunk.
   /// If so, the elements since the previous chunk-starting element
   /// are emitted as a list.
-  /// Any final elements are emitted at the end.
+  /// Any remaining elements are emitted at the end.
   ///
   /// Example:
   /// ```dart
@@ -498,9 +499,10 @@ extension IterableExtension<T> on Iterable<T> {
   ///
   /// Each element and index is checked using [test]
   /// for whether it should end the current chunk.
-  /// If so, the elements since the previous chunk-ending element
+  /// If so, the elements since the previous chunk-ending element,
+  /// includeing the elemenent that satisfied [test],
   /// are emitted as a list.
-  /// Any final elements are emitted at the end, whether the last
+  /// Any remaining elements are emitted at the end, whether the last
   /// element should be split after or not.
   ///
   /// Example:
@@ -529,7 +531,7 @@ extension IterableExtension<T> on Iterable<T> {
   /// checked using [test] for whether a chunk should end between them.
   /// If so, the elements since the previous chunk-splitting elements
   /// are emitted as a list.
-  /// Any final elements are emitted at the end.
+  /// Any remaining elements are emitted at the end.
   ///
   /// Example:
   /// ```dart