Merge "Improve the documentation of toString methods in the java.net package."

4 files changed, 19 insertions, 17 deletions

diff --git a/luni/src/main/java/java/net/InetAddress.java b/luni/src/main/java/java/net/InetAddress.java
index c12a350..cada6bd 100644
--- a/luni/src/main/java/java/net/InetAddress.java
+++ b/luni/src/main/java/java/net/InetAddress.java
@@ -447,13 +447,14 @@ public class InetAddress implements Serializable {
     }
 
     /**
-     * Returns a string containing a concise, human-readable description of this
-     * IP address.
+     * Returns a string containing the host name (if available) and host address.
+     * For example: {@code "www.google.com/74.125.224.115"} or {@code "/127.0.0.1"}.
      *
-     * @return the description, as host/address.
+     * <p>IPv6 addresses may additionally include an interface name or scope id.
+     * For example: {@code "www.google.com/2001:4860:4001:803::1013%eth0"} or
+     * {@code "/2001:4860:4001:803::1013%2"}.
      */
-    @Override
-    public String toString() {
+    @Override public String toString() {
         return (hostName == null ? "" : hostName) + "/" + getHostAddress();
     }
 
diff --git a/luni/src/main/java/java/net/InetSocketAddress.java b/luni/src/main/java/java/net/InetSocketAddress.java
index 01b5301..49dcfc4 100644
--- a/luni/src/main/java/java/net/InetSocketAddress.java
+++ b/luni/src/main/java/java/net/InetSocketAddress.java
@@ -177,13 +177,11 @@ public class InetSocketAddress extends SocketAddress {
     }
 
     /**
-     * Gets a string representation of this socket included the address and the
-     * port number.
-     *
-     * @return the address and port number as a textual representation.
+     * Returns a string containing the address (or the hostname for an
+     * unresolved {@code InetSocketAddress}) and port number.
+     * For example: {@code "www.google.com/74.125.224.115:80"} or {@code "/127.0.0.1:80"}.
      */
-    @Override
-    public String toString() {
+    @Override public String toString() {
         return ((addr != null) ? addr.toString() : hostname) + ":" + port;
     }
 
diff --git a/luni/src/main/java/java/net/InterfaceAddress.java b/luni/src/main/java/java/net/InterfaceAddress.java
index 612eeb4..dea618c 100644
--- a/luni/src/main/java/java/net/InterfaceAddress.java
+++ b/luni/src/main/java/java/net/InterfaceAddress.java
@@ -96,13 +96,11 @@ public class InterfaceAddress {
     }
 
     /**
-     * Returns a string representation for this interface address.
-     * The string is of the form: InetAddress / prefix length [ broadcast address ].
-     *
-     * @return a string representation of this interface address.
+     * Returns a string containing this interface's address, prefix length, and broadcast address.
+     * For example: {@code "/172.18.103.112/23 [/172.18.103.255]"} or
+     * {@code "/0:0:0:0:0:0:0:1%1/128 [null]"}.
      */
-    @Override
-    public String toString() {
+    @Override public String toString() {
         return address + "/" + prefixLength + " [" + broadcastAddress + "]";
     }
 
diff --git a/luni/src/main/java/java/net/NetworkInterface.java b/luni/src/main/java/java/net/NetworkInterface.java
index c6d9af4..e31b74f 100644
--- a/luni/src/main/java/java/net/NetworkInterface.java
+++ b/luni/src/main/java/java/net/NetworkInterface.java
@@ -334,6 +334,11 @@ public final class NetworkInterface extends Object {
         return name.hashCode();
     }
 
+    /**
+     * Returns a string containing details of this network interface.
+     * The exact format is deliberately unspecified. Callers that require a specific
+     * format should build a string themselves, using this class' accessor methods.
+     */
     @Override public String toString() {
         StringBuilder sb = new StringBuilder(25);
         sb.append("[");