Add example for mapError (#29913)

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

@@ -21,6 +21,17 @@ This operators can recover the failure signal, but not the skipped elements, whi
 
 Similarly to `recover` throwing an exception inside `mapError` _will_ be logged on ERROR level automatically.
 
+## Example
+
+The following example demonstrates a stream which throws `ArithmeticException` when the element `0` goes through 
+the `map` operator. The`mapError` is used to transform this exception to `UnsupportedOperationException`.
+
+Scala
+:  @@snip [MapError.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/MapError.scala) { #map-error }
+
+Java
+:  @@snip [MapError.java](/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapError.java) { #map-error }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapError.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2019-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.sourceorflow;
+
+import akka.actor.ActorSystem;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+
+import java.util.Arrays;
+
+public class MapError {
+
+  public static void main(String[] args) {
+
+    // #map-error
+
+    final ActorSystem system = ActorSystem.create("mapError-operator-example");
+    Source.from(Arrays.asList(-1, 0, 1))
+        .map(x -> 1 / x)
+        .mapError(
+            ArithmeticException.class,
+            (ArithmeticException e) ->
+                new UnsupportedOperationException("Divide by Zero Operation is not supported."))
+        .runWith(Sink.seq(), system)
+        .whenComplete(
+            (result, exception) -> {
+              if (result != null) System.out.println(result.toString());
+              else System.out.println(exception.getMessage());
+            });
+
+    // prints "Divide by Zero Operation is not supported."
+    // #map-error
+  }
+}

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

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2019-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.{ Sink, Source }
+
+import scala.concurrent.ExecutionContext
+import scala.util.control.NoStackTrace
+import scala.util.{ Failure, Success }
+
+object MapError extends App {
+
+  implicit val system: ActorSystem = ActorSystem()
+  implicit val ec: ExecutionContext = system.dispatcher
+
+  //#map-error
+  Source(-1 to 1)
+    .map(1 / _)
+    .mapError {
+      case _: ArithmeticException =>
+        new UnsupportedOperationException("Divide by Zero Operation is not supported.") with NoStackTrace
+    }
+    .runWith(Sink.seq)
+    .onComplete {
+      case Success(value) => println(value.mkString)
+      case Failure(ex)    => println(ex.getMessage)
+    }
+
+  // prints "Divide by Zero Operation is not supported."
+  //#map-error
+
+}