Example for Source.fromIterator #25468 (#28582)

* add example for Source.fromIterator #25468

* scala fmt code style fix

* don't use test as a sample for docs

akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md

@@ -19,6 +19,15 @@ for each materialization, which is the reason the @scala[`method`] @java[`factor
 
 If the iterator perform blocking operations, make sure to run it on a separate dispatcher.
 
+## Example
+ 
+Scala
+:   @@snip [From.scala](/akka-docs/src/test/scala/docs/stream/operators/source/From.scala) { #from-iterator }
+
+Java
+:   @@snip [From.java](/akka-docs/src/test/java/jdocs/stream/operators/source/From.java) { #from-iterator }
+
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

akka-docs/src/test/java/jdocs/stream/operators/source/From.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.source;
+
+import akka.actor.ActorSystem;
+import akka.stream.javadsl.Source;
+
+import java.util.Arrays;
+
+public class From {
+
+  private ActorSystem system = null;
+
+  void fromIteratorSample() {
+    // #from-iterator
+    Source.fromIterator(() -> Arrays.asList(1, 2, 3).iterator())
+        .runForeach(System.out::println, system);
+    // could print
+    // 1
+    // 2
+    // 3
+    // #from-iterator
+  }
+}

akka-docs/src/test/scala/docs/stream/operators/source/From.scala

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.source
+
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object From {
+
+  implicit val system: ActorSystem = null
+
+  def fromIteratorSample(): Unit = {
+    //#from-iterator
+    Source.fromIterator(() => (1 to 3).iterator).runForeach(println)
+    // could print
+    // 1
+    // 2
+    // 3
+    //#from-iterator
+  }
+
+}

akka-stream-tests/src/test/java/akka/stream/javadsl/SourceTest.java

@@ -22,6 +22,7 @@ import akka.stream.stage.*;
 import akka.testkit.AkkaSpec;
 import akka.stream.testkit.TestPublisher;
 import akka.testkit.javadsl.TestKit;
+import com.google.common.collect.Iterables;
 import org.junit.ClassRule;
 import org.junit.Test;
 import scala.concurrent.duration.FiniteDuration;
@@ -1157,4 +1158,16 @@ public class SourceTest extends StreamTest {
         akka.stream.scaladsl.Source.empty();
     Source<Integer, NotUsed> javaSource = scalaSource.asJava();
   }
+
+  @Test
+  public void mustProperlyIterate() throws Exception {
+    final Creator<Iterator<Boolean>> input = () -> Iterables.cycle(false, true).iterator();
+
+    final CompletableFuture<List<Boolean>> future =
+        Source.fromIterator(input).grouped(10).runWith(Sink.head(), system).toCompletableFuture();
+
+    assertArrayEquals(
+        new Boolean[] {false, true, false, true, false, true, false, true, false, true},
+        future.get(1, TimeUnit.SECONDS).toArray());
+  }
 }