Doc example for Sink.head (#28782)

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 }

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));

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)