Docs: add code examples for drop and dropWhile Operators (#28613)

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

@@ -16,6 +16,16 @@ Drop `n` elements and then pass any subsequent element downstream.
 
 Drop `n` elements and then pass any subsequent element downstream.
 
+## Example
+
+Given a `Source` of numbers we can drop the first 3 elements with the `drop` operator: 
+
+Scala
+:  @@snip [Drop.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Drop.scala) { #drop }
+
+Java
+:  @@snip [SourceOrFlow.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #drop }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

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

@@ -16,6 +16,17 @@ Drop elements as long as a predicate function return true for the element
 
 Drop elements as long as a predicate function return true for the element
 
+## Example
+
+Given a `Source` of ordered numbers we can drop all the negative ones with the `dropWhile` operator. 
+Mind that after the first non negative number is encountered, all the consecutive elements will be emitted despite the predicate provided.  
+
+Scala
+:  @@snip [Drop.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Drop.scala) { #dropWhile }
+
+Java
+:  @@snip [SourceOrFlow.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #dropWhile }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

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

@@ -386,4 +386,28 @@ class SourceOrFlow {
     // incididunt
     // #filterNot
   }
+
+  void dropExample() {
+    // #drop
+    Source<Integer, NotUsed> fiveIntegers = Source.from(Arrays.asList(1, 2, 3, 4, 5));
+    Source<Integer, NotUsed> droppedThreeInts = fiveIntegers.drop(3);
+
+    droppedThreeInts.runWith(Sink.foreach(System.out::print), system);
+    // 4
+    // 5
+    // #drop
+  }
+
+  void dropWhileExample() {
+    // #dropWhile
+    Source<Integer, NotUsed> droppedWhileNegative =
+        Source.from(Arrays.asList(-3, -2, -1, 0, 1, 2, 3, -1)).dropWhile(integer -> integer < 0);
+
+    droppedWhileNegative.runWith(Sink.foreach(System.out::print), system);
+    // 1
+    // 2
+    // 3
+    // -1
+    // #dropWhile
+  }
 }

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

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2019-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.NotUsed
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object Drop {
+
+  implicit val system: ActorSystem = ActorSystem()
+
+  def drop(): Unit = {
+    // #drop
+    val fiveInts: Source[Int, NotUsed] = Source(1 to 5)
+    val droppedThreeInts: Source[Int, NotUsed] = fiveInts.drop(3)
+
+    droppedThreeInts.runForeach(println)
+    // 4
+    // 5
+    // #drop
+  }
+
+  def dropWhile(): Unit = {
+    // #dropWhile
+    val droppedWhileNegative = Source(-3 to 3).dropWhile(_ < 0)
+
+    droppedWhileNegative.runForeach(println)
+    // 0
+    // 1
+    // 2
+    // 3
+    // #dropWhile
+  }
+
+}