core: clarify dns javadoc/test about trailing path segments

Author: jdcormie

core/src/main/java/io/grpc/internal/DnsNameResolverProvider.java

@@ -33,11 +33,12 @@
  * A provider for {@link DnsNameResolver}.
  *
  * <p>It resolves a target URI whose scheme is {@code "dns"}. The (optional) authority of the target
- * URI is reserved for the address of alternative DNS server (not implemented yet). The first path
- * segment of the hierarchical target URI is interpreted as an RFC 2396 "server-based" authority and
- * used as the "service authority" of the resulting {@link NameResolver}. The "host" part of this
- * authority is the name to be resolved by DNS. The "port" part of this authority (if present) will
- * become the port number for all {@link InetSocketAddress} produced by this resolver. For example:
+ * URI is reserved for the address of alternative DNS server (not implemented yet). The target URI
+ * must be hierarchical and have exactly one path segment which will be interpreted as an RFC 2396
+ * "server-based" authority and used as the "service authority" of the resulting {@link
+ * NameResolver}. The "host" part of this authority is the name to be resolved by DNS. The "port"
+ * part of this authority (if present) will become the port number for all {@link InetSocketAddress}
+ * produced by this resolver. For example:
  *
  * <ul>
  *   <li>{@code "dns:///foo.googleapis.com:8080"} (using default DNS)</li>

core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java

@@ -103,6 +103,8 @@ public void newNameResolver_validDnsNameWithoutPort_usesDefaultPort() {
     assertThat(nameResolver.getPort()).isEqualTo(args.getDefaultPort());
   }
 
+  // TODO(jdcormie): Trailing path segments *should* be forbidden. This test just demonstrates that
+  // both newNameResolver() overloads behave the same with respect to this bug.
   @Test
   public void newNameResolver_toleratesTrailingPathSegments() {
     NameResolver nameResolver = newNameResolver("dns:///foo.googleapis.com/ig/nor/ed", args);