RFR: 8329733: Update the documentation in java.net.SocketOptions to direct to java.net.StandardSocketOptions

[Alan Bateman]

On Fri, 5 Apr 2024 06:56:06 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

> Can I please get a review of this doc-only change which proposes to clean up the documentation of `java.net.SocketOptions` interface?
> 
> As noted in https://bugs.openjdk.org/browse/JDK-8329733, the existing documentation in this legacy interface isn't accurate. The commit in this PR, updates the documentation on several of the fields to point to the newer java.net.StandardSocketOptions class. While at it, I also did a general update of this documentation to use snippets and also reword some of it to be a bit more clear.
> 
> I have run `make docs-image` on this change and the updated doc looks fine to me.

src/java.base/share/classes/java/net/SocketOptions.java line 37:

> 35:  * <P>
> 36:  * The methods and constants defined in this interface are
> 37:  * for internal implementation use only. If you're not subclassing {@code SocketImpl} or

I don't think we can insert the word "internal" here it's part of the exposed interface for this legacy mechanism.

src/java.base/share/classes/java/net/SocketOptions.java line 168:

> 166: 
> 167:     /**
> 168:      * Set the outgoing interface on which to send multicast packets. Useful on hosts with

This option is used to both set and get the outgoing network interface.

src/java.base/share/classes/java/net/SocketOptions.java line 199:

> 197: 
> 198:     /**
> 199:      * Set a timeout on blocking {@code Socket} operations:

This option is also used to set and get the timeout value.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18645#discussion_r1553347140
PR Review Comment: https://git.openjdk.org/jdk/pull/18645#discussion_r1553354819
PR Review Comment: https://git.openjdk.org/jdk/pull/18645#discussion_r1553355367