Summary

Clarify that null is returned when the InterfaceAdrress instance represents an IPv4 loopback address and improve clarity of the class level API documentation.

Problem

The InterfaceAddress.getBroadcast() method specifies that it returns a non-null broadcast address for IPv4 networks and null for IPv6. However, if a loopback IPv4 address is used it also returns null. The specification requires clarification to indicate that null may also be returned for IPv4 addresses that do not support broadcasting. The class level API documentation is unclear to begin with.

Solution

Clarify the current behaviour that IPv4 addresses can too return null via the java documentation and improve wording of class level API doc.

Specification

Update the class level API documentation of the InterfaceAddress class to:

 * This class represents a Network Interface address. In the case of
 * IPv4, this comprises the IP address, a subnet mask, and a broadcast
 * address if the interface supports broadcast. In the case of IPv6,
 * it comprises the IP address and a network prefix length.

Update the java doc comments of the getBroadcast() method of the InterfaceAddress class to include:

      [...]
      * <p>
      * Only IPv4 networks have broadcast address therefore, in the case
      * of an IPv6 network, {@code null} will be returned.
+     * <p>
+     * Certain network interfaces such as the loopback interface, do not support
+     * broadcasting and will also return {@code null}.
      *
      * @return the {@code InetAddress} representing the broadcast
      * address or {@code null} if there is no broadcast address.
      */
     public InetAddress getBroadcast() {