RFR: 8265226: (dc) API note in DatagramChannel.open should link to StandardProtocolFamily.UNIX

[Michael McMahon]

On Thu, 15 Apr 2021 08:51:57 GMT, Michael McMahon <michaelm at openjdk.org> wrote:

>> src/java.base/share/classes/java/nio/channels/DatagramChannel.java line 175:
>> 
>>> 173:      * connected.
>>> 174:      *
>>> 175:      * @apiNote {@link java.net.StandardProtocolFamily#UNIX} is not supported.
>> 
>> It might be clearer to restore the original text ("Unix domain sockets are not support by DatagramChannel") and add something like "; invoking this method with the UNIX protocol family throws UnsupportedOperationException". 
>> 
>> (btw: I had changed the description of the JBS issue to reflect what this issue about, hopefully the commit can use the same description).
>
> I've updated the PR to be the same as the bug report. But, is it necessary to mention UOE, given that the @throws already says:
> 
>      * @throws  UnsupportedOperationException
>      *          If the specified protocol family is not supported. For example,
>      *          suppose the parameter is specified as {@link
>      *          java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6}
>      *          but IPv6 is not enabled on the platform.
> 
> So, maybe just "Unix domain sockets are not supported by DatagramChannel" with the plain link to UDSA?

How about the following?

     * @apiNote {@linkplain java.net.StandardProtocolFamily#UNIX Unix domain}
     *          sockets are not supported.

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

PR: https://git.openjdk.java.net/jdk/pull/3494