expand on sliding doc

be more specific on the more specific overload
include examples

Author: Martijn Hoekstra

library/src/scala/collection/Iterable.scala

@@ -477,26 +477,43 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
 
   /** Groups elements in fixed size blocks by passing a "sliding window"
     *  over them (as opposed to partitioning them, as is done in `grouped`.)
-    *  The "sliding window" step is set to one.
+    *
+    *  An empty collection returns an empty iterator, and a non-empty
+    *  collection containing fewer elements than the window size returns
+    *  an iterator that will produce the original collection as its only
+    *  element.
     *  @see [[scala.collection.Iterator]], method `sliding`
     *
     *  @param size the number of elements per group
-    *  @return An iterator producing ${coll}s of size `size`, except the
-    *          last element (which may be the only element) will be truncated
-    *          if there are fewer than `size` elements remaining to be grouped.
+    *  @return An iterator producing ${coll}s of size `size`, except for a
+    *          non-empty collection with less than `size` elements, which
+    *          returns an iterator that produces the source collection itself
+    *          as its only element.
+    *  @example `List().sliding(2) = empty iterator`
+    *  @example `List(1).sliding(2) = Iterator(List(1))`
+    *  @example `List(1, 2).sliding(2) = Iterator(List(1, 2))`
+    *  @example `List(1, 2, 3).sliding(2) = Iterator(List(1, 2), List(2, 3))`
     */
   def sliding(size: Int): Iterator[C] = sliding(size, 1)
 
   /** Groups elements in fixed size blocks by passing a "sliding window"
     *  over them (as opposed to partitioning them, as is done in grouped.)
+    *
+    *  The returned iterator will be empty when called on an empty collection.
+    *  The last element the iterator produces may be smaller than the window
+    *  size when the original collection isn't exhausted by the window before
+    *  it and its last element isn't skipped by the step before it.
+    *
     *  @see [[scala.collection.Iterator]], method `sliding`
     *
     *  @param size the number of elements per group
     *  @param step the distance between the first elements of successive
     *         groups
-    *  @return An iterator producing ${coll}s of size `size`, except the
-    *          last element (which may be the only element) will be truncated
+    *  @return An iterator producing ${coll}s of size `size`, except the last
+    *          element (which may be the only element) will be smaller
     *          if there are fewer than `size` elements remaining to be grouped.
+    *  @example `List(1, 2, 3, 4, 5).sliding(2, 2) = Iterator(List(1, 2), List(3, 4), List(5))`
+    *  @example `List(1, 2, 3, 4, 5, 6).sliding(2, 3) = Iterator(List(1, 2), List(4, 5))` 
     */
   def sliding(size: Int, step: Int): Iterator[C] =
     iterator.sliding(size, step).map(fromSpecific)

library/src/scala/collection/Iterator.scala

@@ -335,7 +335,7 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite
    *  the second argument `step` is how far to advance the window
    *  on each iteration. The `step` defaults to `1`.
    *
-   *  The default `GroupedIterator` can be configured to either
+   *  The returned `GroupedIterator` can be configured to either
    *  pad a partial result to size `size` or suppress the partial
    *  result entirely.
    *
@@ -353,7 +353,10 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite
    *    (1 to 5).iterator.sliding(4, 3).withPadding(it2.next).toList
    *  }}}
    *
-   *  @return An iterator producing `Seq[B]`s of size `size`, except the
+   *  @param size the number of elements per group
+   *  @param step the distance between the first elements of successive
+   *         groups
+   *  @return A `GroupedIterator` producing `Seq[B]`s of size `size`, except the
    *          last element (which may be the only element) will be truncated
    *          if there are fewer than `size` elements remaining to be grouped.
    *          This behavior can be configured.