On Wed, 7 May 2025 10:29:44 GMT, Jaikiran Pai <j...@openjdk.org> 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