doc: filter and filterNot streams operator, #25468

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

@@ -17,6 +17,18 @@ Filter the incoming elements using a predicate.
 Filter the incoming elements using a predicate. If the predicate returns true the element is passed downstream, if
 it returns false the element is discarded.
 
+See also @ref:[`filterNot`](filterNot.md).
+
+## Example
+
+For example, given a `Source` of words we can select the longer words with the `filter` operator: 
+
+Scala
+:  @@snip [Filter.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Filter.scala) { #filter }
+
+Java
+:  @@snip [SourceOrFlow.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #filter }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

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

@@ -17,6 +17,18 @@ Filter the incoming elements using a predicate.
 Filter the incoming elements using a predicate. If the predicate returns false the element is passed downstream, if
 it returns true the element is discarded.
 
+See also @ref:[`filter`](filter.md).
+
+## Example
+
+For example, given a `Source` of words we can omit the shorter words with the `filterNot` operator: 
+
+Scala
+:  @@snip [Filter.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/Filter.scala) { #filterNot }
+
+Java
+:  @@snip [SourceOrFlow.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #filterNot }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

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

@@ -348,4 +348,44 @@ class SourceOrFlow {
     // 2
     // #take-while
   }
+
+  void filterExample() {
+    // #filter
+    Source<String, NotUsed> words =
+        Source.from(
+            Arrays.asList(
+                ("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt "
+                        + "ut labore et dolore magna aliqua.")
+                    .split(" ")));
+
+    Source<String, NotUsed> longWords = words.filter(w -> w.length() > 6);
+
+    longWords.runWith(Sink.foreach(System.out::print), system);
+    // consectetur
+    // adipiscing
+    // eiusmod
+    // tempor
+    // incididunt
+    // #filter
+  }
+
+  void filterNotExample() {
+    // #filterNot
+    Source<String, NotUsed> words =
+        Source.from(
+            Arrays.asList(
+                ("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt "
+                        + "ut labore et dolore magna aliqua.")
+                    .split(" ")));
+
+    Source<String, NotUsed> longWords = words.filterNot(w -> w.length() <= 5);
+
+    longWords.runWith(Sink.foreach(System.out::print), system);
+    // consectetur
+    // adipiscing
+    // eiusmod
+    // tempor
+    // incididunt
+    // #filterNot
+  }
 }

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

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.NotUsed
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object Filter {
+
+  implicit val system: ActorSystem = ActorSystem()
+
+  def filterExample(): Unit = {
+    // #filter
+    val words: Source[String, NotUsed] =
+      Source(
+        ("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " +
+        "ut labore et dolore magna aliqua.").split(" ").toList)
+
+    val longWords: Source[String, NotUsed] = words.filter(_.length > 6)
+
+    longWords.runForeach(println)
+    // consectetur
+    // adipiscing
+    // eiusmod
+    // tempor
+    // incididunt
+    // #filter
+  }
+
+  def filterNotExample(): Unit = {
+    // #filterNot
+    val words: Source[String, NotUsed] =
+      Source(
+        ("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " +
+        "ut labore et dolore magna aliqua.").split(" ").toList)
+
+    val longWords: Source[String, NotUsed] = words.filterNot(_.length <= 5)
+
+    longWords.runForeach(println)
+    // consectetur
+    // adipiscing
+    // eiusmod
+    // tempor
+    // incididunt
+    // #filterNot
+  }
+}