Improve pool documentation.

redis/pool.go

@@ -35,41 +35,51 @@ var errPoolClosed = errors.New("redigo: connection pool closed")
 //
 // The following example shows how to use a pool in a web application. The
 // application creates a pool at application startup and makes it available to
-// request handlers, possibly using a global variable:
+// request handlers using a global variable.
 //
-//      var server string           // host:port of server
-//      var password string
-//      ...
+//  func newPool(server, password string) *redis.Pool {
+//      return &redis.Pool{
+//          MaxIdle: 3,
+//          IdleTimeout: 240 * time.Second,
+//          Dial: func () (redis.Conn, error) {
+//              c, err := redis.Dial("tcp", server)
+//              if err != nil {
+//                  return nil, err
+//              }
+//              if _, err := c.Do("AUTH", password); err != nil {
+//                  c.Close()
+//                  return nil, err
+//              }
+//              return c, err
+//          },
+//          TestOnBorrow: func(c redis.Conn, t time.Time) error {
+//              _, err := c.Do("PING")
+//              return err
+//          },
+//      }
+//  }
 //
-//      pool = &redis.Pool{
-//              MaxIdle: 3,
-//              IdleTimeout: 240 * time.Second,
-//              Dial: func () (redis.Conn, error) {
-//                  c, err := redis.Dial("tcp", server)
-//                  if err != nil {
-//                      return nil, err
-//                  }
-//                  if _, err := c.Do("AUTH", password); err != nil {
-//                      c.Close()
-//                      return nil, err
-//                  }
-//                  return c, err
-//              },
-//				TestOnBorrow: func(c redis.Conn, t time.Time) error {
-//				    _, err := c.Do("PING")
-//                  return err
-//			    },
-//          }
+//  var (
+//      pool *redis.Pool
+//      redisServer = flag.String("redisServer", ":6379", "")
+//      redisPassword = flag.String("redisPassword", "", "")
+//  )
 //
-// This pool has a maximum of three connections to the server specified by the
-// variable "server". Each connection is authenticated using a password.
+//  func main() {
+//      floag.Parse()
+//      pool = newPool(*redisServer, *redisPassword)
+//      ...
+//  }
 //
 // A request handler gets a connection from the pool and closes the connection
 // when the handler is done:
 //
-//  conn := pool.Get()
-//  defer conn.Close()
-//  // do something with the connection
+//  func serveHome(w http.ResponseWriter, r *http.Request) {
+//      conn := pool.Get()
+//      defer conn.Close()
+//      ....
+//  }
+//
 type Pool struct {
 
 	// Dial is an application supplied function for creating new connections.
@@ -108,8 +118,7 @@ type idleConn struct {
 	t time.Time
 }
 
-// NewPool returns a pool that uses newPool to create connections as needed.
-// The pool keeps a maximum of maxIdle idle connections.
+// NewPool is a convenience function for initializing a pool.
 func NewPool(newFn func() (Conn, error), maxIdle int) *Pool {
 	return &Pool{Dial: newFn, MaxIdle: maxIdle}
 }