--- a/src/java.net.http/share/classes/java/net/http/WebSocket.java	Wed Mar 21 16:50:25 2018 +0000
+++ b/src/java.net.http/share/classes/java/net/http/WebSocket.java	Wed Mar 21 17:10:53 2018 +0000
@@ -336,6 +336,10 @@
          * not more than {@code 125} bytes. These bytes are located from the
          * buffer's position to its limit.
          *
+         * Given that the WebSocket implementation will automatically send a
+         * reciprocal pong when a ping is received, it is rarely required to
+         * send a pong message explicitly when a ping is received.
+         *
          * <p> Return a {@code CompletionStage} which will be used by the
          * {@code WebSocket} as a signal it may reclaim the
          * {@code ByteBuffer}. Do not access the {@code ByteBuffer} after
@@ -568,6 +572,10 @@
      * {@code CompletableFuture} returned from this method the buffer will have
      * no remaining bytes. The buffer must not be accessed until after that.
      *
+     * Given that the WebSocket implementation will automatically send a
+     * reciprocal pong when a ping is received, it is rarely required to send a
+     * pong message explicitly.
+     *
      * <p> The {@code CompletableFuture} returned from this method can
      * complete exceptionally with:
      * <ul>