--- a/src/java.net.http/share/classes/java/net/http/WebSocketHandshakeException.java	Wed Jun 06 15:22:45 2018 +0100
+++ b/src/java.net.http/share/classes/java/net/http/WebSocketHandshakeException.java	Wed Jun 06 15:23:38 2018 +0100
@@ -28,7 +28,7 @@
 import java.io.IOException;
 
 /**
- * An exception used to signal the opening handshake failed.
+ * Thrown when the opening handshake has failed.
  *
  * @since 11
  */
@@ -55,6 +55,10 @@
      * <p> The value may be unavailable ({@code null}) if this exception has
      * been serialized and then deserialized.
      *
+     * @apiNote The primary purpose of this method is to allow programmatic
+     * examination of the reasons behind the failure of the opening handshake.
+     * Some of these reasons might allow recovery.
+     *
      * @return server response
      */
     public HttpResponse<?> getResponse() {