7116990: (spec) Socket.connect(addr,timeout) not clear if IOException because of TCP timeout

Reviewed-by: alanb, dfuchs

Author: jaikiran

src/java.base/share/classes/java/net/Socket.java

@@ -621,6 +621,13 @@ public void connect(SocketAddress endpoint) throws IOException {
      *        {@code SocketException} with the interrupt status set.
      * </ol>
      *
+     * @apiNote Establishing a TCP/IP connection is subject to connect timeout settings
+     * in the operating system. The typical operating system timeout is in the range of tens of
+     * seconds to minutes. If the operating system timeout expires before the
+     * {@code timeout} specified to this method then an {@code IOException} is thrown.
+     * The {@code timeout} specified to this method is typically a timeout value that is
+     * shorter than the operating system timeout.
+     *
      * @param   endpoint the {@code SocketAddress}
      * @param   timeout  the timeout value to be used in milliseconds.
      * @throws  IOException if an error occurs during the connection, the socket