fixes #15 - added tons of new documentation, godoc, and small cosmetic changes to code

- updated readme
- edited and improved godoc comments throughout the code, made them much
  clearer
- function usage in godoc was moved to examples *_test.go files.
  they will be shows in the same adjacent to the function in the godoc.
- some cosmetic changes as well, to comply with gofmt, go vet, golint
- fixed indentation problems
- added function examples and an advanced HTTP GET example
- added new Operation, Notify types to make it easier to understand the
  how the package works

Author: oryband

README.md

@@ -1,57 +1,80 @@
-# backoff
+# Exponential Backoff [![GoDoc][godoc image]][godoc] [![Build Status][travis image]][travis]
 
-[![GoDoc](https://godoc.org/github.com/cenkalti/backoff?status.png)](https://godoc.org/github.com/cenkalti/backoff)
-[![Build Status](https://travis-ci.org/cenkalti/backoff.png)](https://travis-ci.org/cenkalti/backoff)
+This is a Go port of the exponential backoff algorithm from [Google's HTTP Client Library for Java][google-http-java-client].
 
-This is a Go port of the exponential backoff algorithm from
-[google-http-java-client](https://code.google.com/p/google-http-java-client/wiki/ExponentialBackoff).
-
-[Exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff)
+[Exponential backoff][exponential backoff wiki]
 is an algorithm that uses feedback to multiplicatively decrease the rate of some process,
 in order to gradually find an acceptable rate.
 The retries exponentially increase and stop increasing when a certain threshold is met.
 
+## How To
 
+We define two functions, `Retry()` and `RetryNotify()`.
+They receive an `Operation` to execute, a `BackOff` algorithm,
+and an optional `Notify` error handler.
 
+The operation will be executed, and will be retried on failure with delay
+as given by the backoff algorithm. The backoff algorithm can also decide when to stop
+retrying.
+In addition, the notify error handler will be called after each failed attempt,
+except for the last time, whose error should be handled by the caller.
 
-## Install
-
-```bash
-go get github.com/cenkalti/backoff
+```go
+// An Operation is executing by Retry() or RetryNotify().
+// The operation will be retried using a backoff policy if it returns an error.
+type Operation func() error
+
+// Notify is a notify-on-error function. It receives an operation error and
+// backoff delay if the operation failed (with an error).
+//
+// NOTE that if the backoff policy stated to stop retrying,
+// the notify function isn't called.
+type Notify func(error, time.Duration)
+
+func Retry(Operation, BackOff) error
+func RetryNotify(Operation, BackOff, Notify)
 ```
 
-## Example
+## Examples
 
-Simple retry helper that uses exponential back-off algorithm:
+See more advanced examples in the [godoc][advanced example].
+
+### Retry
+
+Simple retry helper that uses the default exponential backoff algorithm:
 
 ```go
 operation := func() error {
-    // An operation that might fail
+    // An operation that might fail.
+    return nil // or return errors.New("some error")
 }
 
-err := backoff.Retry(operation, backoff.NewExponentialBackOff())
+err := Retry(operation, NewExponentialBackOff())
 if err != nil {
-    // handle error
+    // Handle error.
+    return err
 }
 
-// operation is successfull
+// Operation is successful.
+return nil
 ```
 
-Ticker example:
+### Ticker
 
 ```go
 operation := func() error {
-    // An operation that may fail
+    // An operation that might fail
+    return nil // or return errors.New("some error")
 }
 
-b := backoff.NewExponentialBackOff()
-ticker := backoff.NewTicker(b)
+b := NewExponentialBackOff()
+ticker := NewTicker(b)
 
 var err error
 
 // Ticks will continue to arrive when the previous operation is still running,
 // so operations that take a while to fail could run in quick succession.
-for t = range ticker.C {
+for range ticker.C {
     if err = operation(); err != nil {
         log.Println(err, "will retry...")
         continue
@@ -63,7 +86,31 @@ for t = range ticker.C {
 
 if err != nil {
     // Operation has failed.
+    return err
 }
 
-// Operation is successfull.
+// Operation is successful.
+return nil
 ```
+
+## Getting Started
+
+```bash
+# install
+$ go get github.com/cenkalti/backoff
+
+# test
+$ cd $GOPATH/src/github.com/cenkalti/backoff
+$ go get -t ./...
+$ go test -v -cover
+```
+
+[godoc]: https://godoc.org/github.com/cenkalti/backoff
+[godoc image]: https://godoc.org/github.com/cenkalti/backoff?status.png
+[travis]: https://travis-ci.org/cenkalti/backoff
+[travis image]: https://travis-ci.org/cenkalti/backoff.png
+
+[google-http-java-client]: https://github.com/google/google-http-java-client
+[exponential backoff wiki]: http://en.wikipedia.org/wiki/Exponential_backoff
+
+[advanced example]: https://godoc.org/github.com/cenkalti/backoff#example_

adv_example_test.go

@@ -0,0 +1,117 @@
+package backoff
+
+import (
+	"io/ioutil"
+	"log"
+	"net/http"
+	"time"
+)
+
+// This is an example that demonstrates how this package could be used
+// to perform various advanced operations.
+//
+// It executes an HTTP GET request with exponential backoff,
+// while errors are logged and failed responses are closed, as required by net/http package.
+//
+// Note we define a condition function which is used inside the operation to
+// determine whether the operation succeeded or failed.
+func Example() error {
+	res, err := GetWithRetry(
+		"http://localhost:9999",
+		ErrorIfStatusCodeIsNot(http.StatusOK),
+		NewExponentialBackOff())
+
+	if err != nil {
+		// Close response body of last (failed) attempt.
+		// The Last attempt isn't handled by the notify-on-error function,
+		// which closes the body of all the previous attempts.
+		if e := res.Body.Close(); e != nil {
+			log.Printf("error closing last attempt's response body: %s", e)
+		}
+		log.Printf("too many failed request attempts: %s", err)
+		return err
+	}
+	defer res.Body.Close() // The response's Body must be closed.
+
+	// Read body
+	_, _ = ioutil.ReadAll(res.Body)
+
+	// Do more stuff
+	return nil
+}
+
+// GetWithRetry is a helper function that performs an HTTP GET request
+// to the given URL, and retries with the given backoff using the given condition function.
+//
+// It also uses a notify-on-error function which logs
+// and closes the response body of the failed request.
+func GetWithRetry(url string, condition Condition, bck BackOff) (*http.Response, error) {
+	var res *http.Response
+	err := RetryNotify(
+		func() error {
+			var err error
+			res, err = http.Get(url)
+			if err != nil {
+				return err
+			}
+			return condition(res)
+		},
+		bck,
+		LogAndClose())
+
+	return res, err
+}
+
+// Condition is a retry condition function.
+// It receives a response, and returns an error
+// if the response failed the condition.
+type Condition func(*http.Response) error
+
+// ErrorIfStatusCodeIsNot returns a retry condition function.
+// The condition returns an error
+// if the given response's status code is not the given HTTP status code.
+func ErrorIfStatusCodeIsNot(status int) Condition {
+	return func(res *http.Response) error {
+		if res.StatusCode != status {
+			return NewError(res)
+		}
+		return nil
+	}
+}
+
+// Error is returned on ErrorIfX() condition functions throughout this package.
+type Error struct {
+	Response *http.Response
+}
+
+func NewError(res *http.Response) *Error {
+	// Sanity check
+	if res == nil {
+		panic("response object is nil")
+	}
+	return &Error{Response: res}
+}
+func (err *Error) Error() string { return "request failed" }
+
+// LogAndClose is a notify-on-error function.
+// It logs the error and closes the response body.
+func LogAndClose() Notify {
+	return func(err error, wait time.Duration) {
+		switch e := err.(type) {
+		case *Error:
+			defer e.Response.Body.Close()
+
+			b, err := ioutil.ReadAll(e.Response.Body)
+			var body string
+			if err != nil {
+				body = "can't read body"
+			} else {
+				body = string(b)
+			}
+
+			log.Printf("%s: %s", e.Response.Status, body)
+		default:
+			log.Println(err)
+		}
+	}
+}

backoff.go

@@ -5,18 +5,18 @@ package backoff
 
 import "time"
 
-// Back-off policy when retrying an operation.
+// BackOff is a backoff policy for retrying an operation.
 type BackOff interface {
-	// Gets the duration to wait before retrying the operation or
-	// backoff.Stop to indicate that no retries should be made.
+	// NextBackOff returns the duration to wait before retrying the operation,
+	// or backoff.Stop to indicate that no more retries should be made.
 	//
 	// Example usage:
 	//
 	// 	duration := backoff.NextBackOff();
 	// 	if (duration == backoff.Stop) {
-	// 		// do not retry operation
+	// 		// Do not retry operation.
 	// 	} else {
-	// 		// sleep for duration and retry operation
+	// 		// Sleep for duration and retry operation.
 	// 	}
 	//
 	NextBackOff() time.Duration
@@ -28,22 +28,25 @@ type BackOff interface {
 // Indicates that no more retries should be made for use in NextBackOff().
 const Stop time.Duration = -1
 
-// ZeroBackOff is a fixed back-off policy whose back-off time is always zero,
-// meaning that the operation is retried immediately without waiting.
+// ZeroBackOff is a fixed backoff policy whose backoff time is always zero,
+// meaning that the operation is retried immediately without waiting, indefinitely.
 type ZeroBackOff struct{}
 
 func (b *ZeroBackOff) Reset() {}
 
 func (b *ZeroBackOff) NextBackOff() time.Duration { return 0 }
 
-// StopBackOff is a fixed back-off policy that always returns backoff.Stop for
-// NextBackOff(), meaning that the operation should not be retried.
+// StopBackOff is a fixed backoff policy that always returns backoff.Stop for
+// NextBackOff(), meaning that the operation should never be retried.
 type StopBackOff struct{}
 
 func (b *StopBackOff) Reset() {}
 
 func (b *StopBackOff) NextBackOff() time.Duration { return Stop }
 
+// ConstantBackOff is a backoff policy that always returns the same backoff delay.
+// This is in contrast to an exponential backoff policy,
+// which returns a delay that grows longer as you call NextBackOff() over and over again.
 type ConstantBackOff struct {
 	Interval time.Duration
 }

backoff_test.go

@@ -1,9 +1,8 @@
 package backoff
 
 import (
-	"time"
-
 	"testing"
+	"time"
 )
 
 func TestNextBackOffMillis(t *testing.T) {

example_test.go

@@ -0,0 +1,51 @@
+package backoff
+
+import "log"
+
+func ExampleRetry() error {
+	operation := func() error {
+		// An operation that might fail.
+		return nil // or return errors.New("some error")
+	}
+
+	err := Retry(operation, NewExponentialBackOff())
+	if err != nil {
+		// Handle error.
+		return err
+	}
+
+	// Operation is successful.
+	return nil
+}
+
+func ExampleTicker() error {
+	operation := func() error {
+		// An operation that might fail
+		return nil // or return errors.New("some error")
+	}
+
+	b := NewExponentialBackOff()
+	ticker := NewTicker(b)
+
+	var err error
+
+	// Ticks will continue to arrive when the previous operation is still running,
+	// so operations that take a while to fail could run in quick succession.
+	for range ticker.C {
+		if err = operation(); err != nil {
+			log.Println(err, "will retry...")
+			continue
+		}
+
+		ticker.Stop()
+		break
+	}
+
+	if err != nil {
+		// Operation has failed.
+		return err
+	}
+
+	// Operation is successful.
+	return nil
+}