On Wed, 7 May 2025 10:29:44 GMT, Jaikiran Pai <[email protected]> wrote:
>> src/java.base/share/classes/java/net/Socket.java line 390:
>>
>>> 388: * The {@code stream} parameter provided a way in early JDK
>>> releases
>>> 389: * to create a {@code Socket} that used a datagram socket. This
>>> feature
>>> 390: * no longer exists.
>>
>> Should we also re-iterate here that this constructor is deprecated? It kind
>> of feels like this information should be in `@deprecated` instead, or that
>> it should say that IAE is being thrown...
>
> Hello Daniel, do you mean something like this:
>
> - * @apiNote
> - * The {@code stream} parameter provided a way in early JDK releases
> - * to create a {@code Socket} that used a datagram socket. This feature
> - * no longer exists.
> - *
> * @param host the IP address.
> * @param port the port number.
> * @param stream must be true, false is not allowed.
> @@ -429,7 +424,9 @@ public Socket(String host, int port, boolean stream)
> throws IOException {
> * or if the port parameter is outside the specified range
> of valid
> * port values, which is between 0 and 65535, inclusive.
> * @throws NullPointerException if {@code host} is null.
> - * @deprecated Use {@link DatagramSocket} instead for UDP transport.
> + * @deprecated The {@code stream} parameter provided a way in early JDK
> releases
> + * to create a {@code Socket} that used a datagram socket.
> This feature
> + * no longer exists. Use {@link DatagramSocket} instead for
> UDP transport.
>
>
> Having that text in `@deprecated` does convey the reason for deprecation and
> does show up prominently in the rendered javadoc:
>
> <img width="1097" alt="doc"
> src="https://github.com/user-attachments/assets/897e581e-28c4-424c-b3f9-3bce4591cb7e";
> />
>
>
> So if you and others think we should remove the apiNote and move the text to
> deprecated, then I'll update the PR and the CSR.
Okay with me but for SocketImpl then I think it has to be an apiNote as the
create method is not deprecated.
BTW: "Use DatagramSocket instead for UDP transport" switches the terminology.
The first sentence uses "datagram socket" so I best to use that in the second
sentence to avoid "UDP" and "transport".
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/25031#discussion_r2077331080
