Merge pull request #164 from hashicorp/docs

improve docs for response handlers

README.md

@@ -45,25 +45,6 @@ The returned response object is an `*http.Response`, the same thing you would
 usually get from `net/http`. Had the request failed one or more times, the above
 call would block and retry with exponential backoff.
 
-## Retrying cases that fail after a seeming success
-
-It's possible for a request to succeed in the sense that the expected response headers are received, but then to encounter network-level errors while reading the response body. In go-retryablehttp's most basic usage, this error would not be retryable, due to the out-of-band handling of the response body. In some cases it may be desirable to handle the response body as part of the retryable operation.
-
-A toy example (which will retry the full request and succeed on the second attempt) is shown below:
-
-```go
-c := retryablehttp.NewClient()
-r := retryablehttp.NewRequest("GET", "://foo", nil)
-handlerShouldRetry := true
-r.SetResponseHandler(func(*http.Response) error {
-    if !handlerShouldRetry {
-        return nil
-    }
-    handlerShouldRetry = false
-    return errors.New("retryable error")
-})
-```
-
 ## Getting a stdlib `*http.Client` with retries
 
 It's possible to convert a `*retryablehttp.Client` directly to a `*http.Client`.

client.go

@@ -80,8 +80,15 @@ var (
 type ReaderFunc func() (io.Reader, error)
 
 // ResponseHandlerFunc is a type of function that takes in a Response, and does something with it.
-// It only runs if the initial part of the request was successful.
-// If an error is returned, the client's retry policy will be used to determine whether to retry the whole request.
+// The ResponseHandlerFunc is called when the HTTP client successfully receives a response and the
+// CheckRetry function indicates that a retry of the base request is not necessary.
+// If an error is returned from this function, the CheckRetry policy will be used to determine
+// whether to retry the whole request (including this handler).
+//
+// Make sure to check status codes! Even if the request was completed it may have a non-2xx status code.
+//
+// The response body is not automatically closed. It must be closed either by the ResponseHandlerFunc or
+// by the caller out-of-band. Failure to do so will result in a memory leak.
 type ResponseHandlerFunc func(*http.Response) error
 
 // LenReader is an interface implemented by many in-memory io.Reader's. Used