+doc #20521 Enrich docs and tests regarding empty strings used in matchers (#20719)

akka-docs/rst/java/http/routing-dsl/directives/path-directives/path.rst

@@ -24,6 +24,10 @@ a ``path`` directive will always be empty).
 Depending on the type of its ``PathMatcher`` argument the ``path`` directive extracts zero or more values from the URI.
 If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.
 
+.. note:: The empty string (also called empty word or identity) is a **neutral element** of string concatenation operation,
+ so it will match everything, but remember that ``path`` requires whole remaining path being matched, so (``/``) will succeed
+ and (``/whatever``) will fail. The :ref:`-pathPrefix-java-` provides more liberal behaviour.
+
 
 Example
 -------

akka-docs/rst/java/http/routing-dsl/directives/path-directives/pathPrefix.rst

@@ -18,6 +18,9 @@ As opposed to its :ref:`-rawPathPrefix-java-` counterpart ``pathPrefix`` automat
 Depending on the type of its ``PathMatcher`` argument the ``pathPrefix`` directive extracts zero or more values from
 the URI. If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.
 
+.. note:: The empty string (also called empty word or identity) is a **neutral element** of string concatenation operation,
+ so it will match everything and consume nothing. The :ref:`-path-java-` provides more strict behaviour.
+
 
 Example
 -------

akka-docs/rst/scala/http/routing-dsl/directives/path-directives/path.rst

@@ -31,6 +31,10 @@ a ``path`` directive will always be empty).
 Depending on the type of its ``PathMatcher`` argument the ``path`` directive extracts zero or more values from the URI.
 If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.
 
+.. note:: The empty string (also called empty word or identity) is a **neutral element** of string concatenation operation,
+ so it will match everything, but remember that ``path`` requires whole remaining path being matched, so (``/``) will succeed
+ and (``/whatever``) will fail. The :ref:`-pathPrefix-` provides more liberal behaviour.
+
 
 Example
 -------

akka-docs/rst/scala/http/routing-dsl/directives/path-directives/pathPrefix.rst

@@ -25,6 +25,9 @@ As opposed to its :ref:`-rawPathPrefix-` counterpart ``pathPrefix`` automaticall
 Depending on the type of its ``PathMatcher`` argument the ``pathPrefix`` directive extracts zero or more values from
 the URI. If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.
 
+.. note:: The empty string (also called empty word or identity) is a **neutral element** of string concatenation operation,
+ so it will match everything and consume nothing. The :ref:`-path-` provides more strict behaviour.
+
 
 Example
 -------

akka-http-tests/src/test/scala/akka/http/scaladsl/server/directives/PathDirectivesSpec.scala

@@ -22,6 +22,34 @@ class PathDirectivesSpec extends RoutingSpec with Inside {
     "reject [/foo/]" in test()
   }
 
+  """pathPrefix("")""" should {
+    val test = testFor(pathPrefix("") { echoUnmatchedPath })
+
+    // Should match everything because pathPrefix is used and "" is a neutral element.
+    "accept [/] and clear the unmatchedPath=" in test("")
+    "accept [/foo] and clear the unmatchedPath" in test("foo")
+    "accept [/foo/] and clear the unmatchedPath" in test("foo/")
+    "accept [/bar/] and clear the unmatchedPath" in test("bar/")
+  }
+
+  """path("" | "foo")""" should {
+    val test = testFor(path("" | "foo") { echoUnmatchedPath })
+
+    // Should not match anything apart of "/", because path requires whole path being matched.
+    "accept [/] and clear the unmatchedPath=" in test("")
+    "reject [/foo]" in test()
+    "reject [/foo/]" in test()
+    "reject [/bar/]" in test()
+  }
+
+  """path("") ~ path("foo")""" should {
+    val test = testFor(path("")(echoUnmatchedPath) ~ path("foo")(echoUnmatchedPath))
+
+    // Should match both because ~ operator is used for two exclusive routes.
+    "accept [/] and clear the unmatchedPath=" in test("")
+    "accept [/foo] and clear the unmatchedPath=" in test("")
+  }
+
   """path("foo" /)""" should {
     val test = testFor(path("foo" /) { echoUnmatchedPath })
     "reject [/foo]" in test()