8241995: Clarify InetSocketAddress::toString specification

Reviewed-by: michaelm, chegar

src/java.base/share/classes/java/net/InetSocketAddress.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -373,11 +373,18 @@ public final boolean isUnresolved() {
 
     /**
      * Constructs a string representation of this InetSocketAddress.
-     * This String is constructed by calling toString() on the InetAddress
-     * and concatenating the port number (with a colon). If the address
-     * is an IPv6 address, the IPv6 literal is enclosed in square brackets.
+     * This string is constructed by calling {@link InetAddress#toString()}
+     * on the InetAddress and concatenating the port number (with a colon).
+     * <p>
+     * If the address is an IPv6 address, the IPv6 literal is enclosed in
+     * square brackets, for example: {@code "localhost/[0:0:0:0:0:0:0:1]:80"}.
      * If the address is {@linkplain #isUnresolved() unresolved},
-     * {@code <unresolved>} is displayed in place of the address literal.
+     * {@code <unresolved>} is displayed in place of the address literal, for
+     * example {@code "foo/<unresolved>:80"}.
+     * <p>
+     * To retrieve a string representation of the hostname or the address, use
+     * {@link #getHostString()}, rather than parsing the string returned by this
+     * {@link #toString()} method.
      *
      * @return  a string representation of this object.
      */