Clarify documentation on closing WebSockets and Responses.

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();
   }
 

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);
   }
 }