8209992: Align SSLSocket and SSLEngine Javadocs

src/java.base/share/classes/javax/net/ssl/SSLEngine.java

@@ -1088,7 +1088,17 @@ public SSLSession getHandshakeSession() {
 
 
     /**
-     * Initiates handshaking (initial or renegotiation) on this SSLEngine.
+     * Begins handshaking on this {@code SSLEngine}.
+     * <P>
+     * Common reasons include a need to initiate a new protected session,
+     * create new encryption keys, or to change cipher suites. To force
+     * complete reauthentication, the current session should be invalidated
+     * before starting this handshake.
+     * <P>
+     * The behavior of this method is protocol (and possibly implementation)
+     * dependent. For example, in TLSv1.3 calling this method after the
+     * connection has been established will force a key update. For prior TLS
+     * versions it will force a renegotiation (re-handshake).
      * <P>
      * This method is not needed for the initial handshake, as the
      * {@code wrap()} and {@code unwrap()} methods will

src/java.base/share/classes/javax/net/ssl/SSLSocket.java

@@ -502,15 +502,22 @@ public abstract void removeHandshakeCompletedListener(
 
 
     /**
-     * Starts an SSL handshake on this connection.  Common reasons include
-     * a need to use new encryption keys, to change cipher suites, or to
-     * initiate a new session.  To force complete reauthentication, the
-     * current session could be invalidated before starting this handshake.
-     *
-     * <P> If data has already been sent on the connection, it continues
+     * Starts handshaking on this {@code SSLSocket}.
+     * <P>
+     * Common reasons include a need to initiate a new protected session,
+     * create new encryption keys, or to change cipher suites. To force
+     * complete reauthentication, the current session should be invalidated
+     * before starting this handshake.
+     * <P>
+     * The behavior of this method is protocol (and possibly implementation)
+     * dependent. For example, in TLSv1.3 calling this method after the
+     * connection has been established will force a key update. For prior TLS
+     * versions it will force a renegotiation (re-handshake).
+     * <P>
+     * If data has already been sent on the connection, it continues
      * to flow during this handshake.  When the handshake completes, this
      * will be signaled with an event.
-     *
+     * <P>
      * This method is synchronous for the initial handshake on a connection
      * and returns when the negotiated handshake is complete. Some
      * protocols may not support multiple handshakes on an existing socket