8241995: Clarify InetSocketAddress::toString specification
Reviewed-by: michaelm, chegar
diff --git a/src/java.base/share/classes/java/net/InetSocketAddress.java b/src/java.base/share/classes/java/net/InetSocketAddress.java
index 7eb0273..56635cb 100644
--- a/src/java.base/share/classes/java/net/InetSocketAddress.java
+++ b/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 @@
/**
* 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.
*/
