From 1545f3fb2577c2e22f1743439ec64164f10d42d6 Mon Sep 17 00:00:00 2001
From: B YI <uuuuuu@protonmail.com>
Date: Mon, 23 Mar 2020 21:03:09 +0800
Subject: [PATCH] Doc example for Sink.head (#28782)

---
 .../src/main/paradox/stream/operators/Sink/head.md    |  8 ++++++++
 .../java/jdocs/stream/operators/SinkDocExamples.java  |  9 +++++++++
 .../scala/akka/stream/scaladsl/HeadSinkSpec.scala     | 11 +++++++++++
 3 files changed, 28 insertions(+)

diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/head.md b/akka-docs/src/main/paradox/stream/operators/Sink/head.md
index ec9d82d307..026ef08460 100644
--- a/akka-docs/src/main/paradox/stream/operators/Sink/head.md
+++ b/akka-docs/src/main/paradox/stream/operators/Sink/head.md
@@ -17,6 +17,14 @@ Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes wi
 Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving,
 after this the stream is canceled. If no element is emitted, the @scala[`Future`] @java[`CompletionStage`] is failed.
 
+## Example
+
+Scala
+:   @@snip [HeadSinkSpec.scala](/akka-stream-tests/src/test/scala/akka/stream/scaladsl/HeadSinkSpec.scala) { #head-operator-example }
+
+Java
+:   @@snip [SinkDocExamples.java](/akka-docs/src/test/java/jdocs/stream/operators/SinkDocExamples.java) { #head-operator-example }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }
diff --git a/akka-docs/src/test/java/jdocs/stream/operators/SinkDocExamples.java b/akka-docs/src/test/java/jdocs/stream/operators/SinkDocExamples.java
index ac97a216c0..e0d05d94af 100644
--- a/akka-docs/src/test/java/jdocs/stream/operators/SinkDocExamples.java
+++ b/akka-docs/src/test/java/jdocs/stream/operators/SinkDocExamples.java
@@ -78,6 +78,15 @@ public class SinkDocExamples {
     // #takeLast-operator-example
   }
 
+  static void headExample() {
+    // #head-operator-example
+    Source<Integer, NotUsed> source = Source.from(Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
+    CompletionStage<Integer> result = source.runWith(Sink.head(), system);
+    result.thenAccept(System.out::println);
+    // 1
+    // #head-operator-example
+  }
+
   static void lastExample() {
     // #last-operator-example
     Source<Integer, NotUsed> source = Source.from(Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
diff --git a/akka-stream-tests/src/test/scala/akka/stream/scaladsl/HeadSinkSpec.scala b/akka-stream-tests/src/test/scala/akka/stream/scaladsl/HeadSinkSpec.scala
index 53d8e88c46..66f379cbe4 100644
--- a/akka-stream-tests/src/test/scala/akka/stream/scaladsl/HeadSinkSpec.scala
+++ b/akka-stream-tests/src/test/scala/akka/stream/scaladsl/HeadSinkSpec.scala
@@ -19,6 +19,17 @@ class HeadSinkSpec extends StreamSpec("""
 
   "A Flow with Sink.head" must {
 
+    "yield the first value for simple source" in {
+      implicit val ec = system.dispatcher
+      //#head-operator-example
+      val source = Source(1 to 10)
+      val result: Future[Int] = source.runWith(Sink.head)
+      result.map(println)
+      // 1
+      //#head-operator-example
+      result.futureValue shouldEqual 1
+    }
+
     "yield the first value" in assertAllStagesStopped {
       val p = TestPublisher.manualProbe[Int]()
       val f: Future[Int] = Source.fromPublisher(p).map(identity).runWith(Sink.head)