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

[Alan Bateman]

On Thu, 15 Apr 2021 09:22:37 GMT, Michael McMahon <michaelm at openjdk.org> wrote:

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

My concern with linking to UDSA is that it's a SocketAddress and the parameter is a ProtocolFamily. So if there is a link then I think it should be to StandardProtocolFamily#UNIX. The text above 'Unix domain sockets are not supported by DatagramSocket" without a link is okay too.

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

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