8209992: Align SSLSocket and SSLEngine Javadocs

Reviewed-by: wetmore

Author: artur-oracle

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
@@ -1102,9 +1112,6 @@ public SSLSession getHandshakeSession() {
      * SSLSocket#startHandshake()} method, this method does not block
      * until handshaking is completed.
      * <P>
-     * To force a complete SSL/TLS/DTLS session renegotiation, the current
-     * session should be invalidated prior to calling this method.
-     * <P>
      * Some protocols may not support multiple handshakes on an existing
      * engine and may throw an {@code SSLException}.
      *

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

@@ -502,19 +502,26 @@ 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
-     * and may throw an IOException.
+     * and may throw an {@code IOException}.
      *
      * @throws IOException on a network level error
      * @see #addHandshakeCompletedListener(HandshakeCompletedListener)