On Tue, 6 May 2025 15:22:02 GMT, Daniel Fuchs <dfu...@openjdk.org> wrote:
>> Jaikiran Pai has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Michael's review suggestions
>
> 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.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/25031#discussion_r2077324431
