Add grouped example to akka-docs (#25468) (#28013)

akka-docs/src/main/paradox/stream/operators/Source-or-Flow/grouped.md

@@ -29,3 +29,13 @@ elements downstream.
 
 @@@
 
+## Examples
+
+Below example demonstrates how `grouped` groups the accumulated elements into @scala[`Seq`] @java[`List`]
+and maps with other operation.
+
+Scala
+:  @@snip [Grouped.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Grouped.scala) { #grouped }
+
+Java
+:  @@snip [SourceOrFlow.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #grouped }

akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java

@@ -252,4 +252,23 @@ class SourceOrFlow {
             .map(p -> new Pong(p.id));
     // #collectType
   }
+
+  void groupedExample() {
+    // #grouped
+    Source.from(Arrays.asList(1, 2, 3, 4, 5, 6, 7))
+        .grouped(3)
+        .runForeach(System.out::println, materializer);
+    // [1, 2, 3]
+    // [4, 5, 6]
+    // [7]
+
+    Source.from(Arrays.asList(1, 2, 3, 4, 5, 6, 7))
+        .grouped(3)
+        .map(g -> g.stream().reduce(0, Integer::sum))
+        .runForeach(System.out::println, materializer);
+    // 6   (= 1 + 2 + 3)
+    // 15  (= 4 + 5 + 6)
+    // 7   (= 7)
+    // #grouped
+  }
 }

akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Grouped.scala

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+import akka.stream.scaladsl.Source
+
+object Grouped {
+  def groupedExample(): Unit = {
+    import akka.actor.ActorSystem
+
+    implicit val system: ActorSystem = ActorSystem()
+
+    //#grouped
+    Source(1 to 7).grouped(3).runForeach(println)
+    // Vector(1, 2, 3)
+    // Vector(4, 5, 6)
+    // Vector(7)
+
+    Source(1 to 7).grouped(3).map(_.sum).runForeach(println)
+    // 6   (= 1 + 2 + 3)
+    // 15  (= 4 + 5 + 6)
+    // 7   (= 7)
+    //#grouped
+  }
+
+}