From c133700e32118c8c32516c5137ece684fee713bc Mon Sep 17 00:00:00 2001
From: jwilson <jwilson@squareup.com>
Date: Sat, 10 Jun 2017 10:32:01 -0400
Subject: [PATCH] Clarify documentation on closing WebSockets and Responses.

Closes: https://github.com/square/okhttp/issues/3383
Closes: https://github.com/square/okhttp/issues/3386
---
 okhttp/src/main/java/okhttp3/Response.java  | 11 ++++++++++-
 okhttp/src/main/java/okhttp3/WebSocket.java |  6 ++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/okhttp/src/main/java/okhttp3/Response.java b/okhttp/src/main/java/okhttp3/Response.java
index 31475178aece..1e3ab454a5ce 100644
--- a/okhttp/src/main/java/okhttp3/Response.java
+++ b/okhttp/src/main/java/okhttp3/Response.java
@@ -269,8 +269,17 @@ public long receivedResponseAtMillis() {
     return receivedResponseAtMillis;
   }
 
-  /** Closes the response body. Equivalent to {@code body().close()}. */
+  /**
+   * Closes the response body. Equivalent to {@code body().close()}.
+   *
+   * <p>It is an error to close a response that is not eligible for a body. This includes the
+   * responses returned from {@link #cacheResponse}, {@link #networkResponse}, and {@link
+   * #priorResponse()}.
+   */
   @Override public void close() {
+    if (body == null) {
+      throw new IllegalStateException("response is not eligible for a body and must not be closed");
+    }
     body.close();
   }
 
diff --git a/okhttp/src/main/java/okhttp3/WebSocket.java b/okhttp/src/main/java/okhttp3/WebSocket.java
index 54cf6f402212..83b585c96819 100644
--- a/okhttp/src/main/java/okhttp3/WebSocket.java
+++ b/okhttp/src/main/java/okhttp3/WebSocket.java
@@ -111,6 +111,12 @@ public interface WebSocket {
   void cancel();
 
   interface Factory {
+    /**
+     * Creates a new web socket and immediately returns it. Creating a web socket initiates an
+     * asynchronous process to connect the socket. Once that succeeds or fails, {@code listener}
+     * will be notified. The caller must either close or cancel the returned web socket when it is
+     * no longer in use.
+     */
     WebSocket newWebSocket(Request request, WebSocketListener listener);
   }
 }