RFR: JDK-8241995: Clarify InetSocketAddress::toString specification [v2]

[Alan Bateman]

On Wed, 3 Feb 2021 14:17:58 GMT, Julia Boes <jboes at openjdk.org> wrote:

>> This change clarifies the InetSocketAddress::toString specification, which was recently updated to reflect an implementation change [1]. The specification is not changed, but it is enhanced with two examples and some more verbiage, as per earlier suggestions on the net-dev mailing list [2][3].
>> 
>> [1] https://bugs.openjdk.java.net/browse/JDK-8225499
>> [2] https://mail.openjdk.java.net/pipermail/net-dev/2020-April/013776.html
>> [3] https://mail.openjdk.java.net/pipermail/net-dev/2021-February/015297.html
>
> Julia Boes has updated the pull request incrementally with one additional commit since the last revision:
> 
>   small adjustment

src/java.base/share/classes/java/net/InetSocketAddress.java line 387:

> 385:      * To retrieve a string representation of the hostname or the address, use
> 386:      * {@link #getHostString()}, rather than parsing the string returned by this
> 387:      * {@link #toString()} method.

A couple of small suggestions:
- "This string" -> "The string"
- For the IPv6 literal case it would good to make it clear that it is enclosed in square brackets before append the colon and port. It might also be better to not have this in a separate paragraph because it follows immediately from the previous sentence.
- The final sentence "To retrieve ..." might be better starting with "Use getHostString to get the String representation ..."

-------------

PR: https://git.openjdk.java.net/jdk/pull/2357