docs and examples like a responsible author

README.md

@@ -1,7 +1,9 @@
 go-hostpool
 ===========
 
-Intelligently and flexibly pool among multiple hosts from your Go application.
+A Go package to intelligently and flexibly pool among multiple hosts from your Go application.
+Host selection can operate in round robin or epsilon greedy mode, and unresponsive hosts are
+avoided.
 Usage example:
 
 ```go
@@ -12,4 +14,4 @@ err := _ // (make a request with hostname)
 hostResponse.Mark(err)
 ```
 
-View more detailed documentation on godoc.org
+View more detailed documentation on [godoc.org](http://godoc.org/github.com/bitly/go-hostpool)

example_test.go

@@ -0,0 +1,13 @@
+package hostpool_test
+
+import (
+	"github.com/bitly/go-hostpool"
+)
+
+func Example_epsilon_greedy() {
+	hp := hostpool.NewEpsilonGreedy([]string{"a", "b"}, 0, &hostpool.LinearEpsilonValueCalculator{})
+	hostResponse := hp.Get()
+	hostname := hostResponse.Host()
+	err := _ // (make a request with hostname)
+	hostResponse.Mark(err)
+}

hostpool.go

@@ -1,3 +1,6 @@
+// A Go package to intelligently and flexibly pool among multiple hosts from your Go application.
+// Host selection can operate in round robin or epsilon greedy mode, and unresponsive hosts are
+// avoided. A good overview of Epsilon Greedy is here http://stevehanov.ca/blog/index.php?id=132
 package hostpool
 
 import (