RFR: 8283779: Clarify API documentation of NetworkInterface with respect to configuration changes [v4]

[Daniel Fuchs]

On Tue, 3 Sep 2024 11:15:52 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> Please find here a change that adds a few `@apiNote` and `@implNote` to `NetworkInterface` to clarify user expectation and implementation.
>
> Daniel Fuchs has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Update src/java.base/share/classes/java/net/NetworkInterface.java
>    
>    Co-authored-by: Daniel Jelinski <djelinski1 at gmail.com>
>  - Update src/java.base/share/classes/java/net/NetworkInterface.java
>    
>    Co-authored-by: Daniel Jelinski <djelinski1 at gmail.com>

src/java.base/share/classes/java/net/NetworkInterface.java line 118:

> 116:      *
> 117:      * @implNote
> 118:      * The returned array contains all or a subset of the InetAddresses that were

Suggestion:

     * The returned enumeration contains all or a subset of the InetAddresses that were

src/java.base/share/classes/java/net/NetworkInterface.java line 283:

> 281:      * configuration taken at the time the instance is created.
> 282:      * To see updates to the configuration may, or may not, require
> 283:      * obtaining a new instance of the interface.

Suggestion:

     * The network configuration may change at any time, and this method may need to
     * be invoked again to obtain a more up to date view of the network interface.

src/java.base/share/classes/java/net/NetworkInterface.java line 315:

> 313:      * configuration taken at the time the instance is created.
> 314:      * To see updates to the configuration may, or may not, require
> 315:      * obtaining a new instance of the interface.

Suggestion:

     * The network configuration may change at any time, and this method may need to
     * be invoked again to obtain a more up to date view of the network interface.

src/java.base/share/classes/java/net/NetworkInterface.java line 348:

> 346:      * configuration taken at the time the instance is created.
> 347:      * To see updates to the configuration may, or may not, require
> 348:      * obtaining a new instance of the interface.

Suggestion:

     * The network configuration may change at any time, and this method may need to
     * be invoked again to obtain a more up to date view of the network interface.

src/java.base/share/classes/java/net/NetworkInterface.java line 401:

> 399:      * configuration taken at the time the instance is created.
> 400:      * To see updates to the configuration may, or may not, require
> 401:      * obtaining new instances of the interfaces.

Suggestion:

     * The network configuration may change at any time, and this method may need to
     * be invoked again to obtain a more up to date view of the network interface.

src/java.base/share/classes/java/net/NetworkInterface.java line 440:

> 438:      * configuration taken at the time the instance is created.
> 439:      * To see updates to the configuration may, or may not, require
> 440:      * obtaining new instances of the interfaces.

Suggestion:

     * The network configuration may change at any time, and this method may need to
     * be invoked again to obtain a more up to date view of the network interface.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741876095
PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741879133
PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741881385
PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741881617
PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741882109
PR Review Comment: https://git.openjdk.org/jdk/pull/20822#discussion_r1741882677