RFR: 8356395: Spec needs to be clarified for InterfaceAddress.getBroadcast() method [v2]

[Michael McMahon]

On Fri, 9 May 2025 10:02:25 GMT, kieran-farrell <duke at openjdk.org> wrote:

>> src/java.base/share/classes/java/net/InterfaceAddress.java line 67:
>> 
>>> 65:      * <p>
>>> 66:      * Certain IPv4 addresses, such as the loopback address, do not support
>>> 67:      * broadcasting and will also result in {@code null} being returned.
>> 
>> Suggestion:
>> 
>>      * Certain network interfaces, such as the loopback interface, do not support
>>      * broadcasting and will also return {@code null}.
>> 
>> 
>> Maybe the class level API documentation should also be updated something like:
>> 
>> 
>>  * This class represents a Network Interface address. In short it's an
>>  * IP address, a subnet mask as well as a broadcast address when the address is
>>  * IPv4 and the interface supports broadcasting.
>>  * An IP address and a network prefix length in the case
>>  * of IPv6 address.
>> 
>> 
>> It would be good to have @Michael-Mc-Mahon approve the wording.
>
> Thanks Daniel, I have commited the above change in wording to the get broadcast method and updated the CSR to reflect (JDK-8356002). I will await confirmation on the class level API documentation before updating.

I think the original wording of the class level doc was phrased awkwardly. I'd like to suggest the following:

 * 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.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25095#discussion_r2086419179