Add more comprehensive description of the TestRoute run methods

Document in greater detail the difference between `run` and
`runWithRejections`.

akka-http-testkit/src/main/scala/akka/http/javadsl/testkit/TestRoute.scala

@@ -19,14 +19,25 @@ trait TestRoute {
   def underlying: Route
 
   /**
-   * Run the request against the sealed route, meaning use a default handler
-   * as a fallback for all cases the route doesn’t handle itself.
+   * Run the request against the sealed route, meaning that exceptions and rejections will be handled by
+   * the default exception and rejection handlers. The default handlers will convert exceptions and
+   * rejections into HTTP responses with corresponding status codes (like 404 when no route matches
+   * the path or 500 in cases of exceptions).
+   *
+   * If you want to assert on the original rejections instead, use [[TestRoute#runWithRejections]].
    */
   def run(request: HttpRequest): TestRouteResult
 
   /**
-   * Run the request against the semi-sealed route, meaning that a default
-   * handler is used for exceptions but not for rejections.
+   * Run the request against the "semi-sealed" route, meaning that exceptions will be handled by the
+   * default exception handler but rejections will not be handled. This means that the test will not
+   * see HTTP responses with error status codes for routes that rejected a request. Instead, the
+   * [[TestRouteResult]] allows access to the original rejection containing all the rejection details
+   * in structured form. Use [[TestRouteResult#assertRejections]] to check that a route rejected a
+   * request with expected rejections.
+   *
+   * Otherwise, to assert on the actual error HTTP response generated by the default rejection handler,
+   * use the [[TestRoute#run]] method, instead.
    */
   def runWithRejections(request: HttpRequest): TestRouteResult
 }