Improve documentation about errors

redis/doc.go

@@ -165,4 +165,13 @@
 //   if _, err := redis.Scan(reply, &value1, &value2); err != nil {
 //      // handle error
 //  }
+//
+// Errors
+//
+// Connection methods return error replies from the server as type redis.Error.
+//
+// Call the connection Err() method to determine if the connection encountered
+// non-recoverable error such as a network error or protocol parsing error. If
+// Err() returns a non-nil value, then the connection is not usable and should
+// be closed.
 package redis // import "github.com/garyburd/redigo/redis"

redis/redis.go

@@ -24,10 +24,7 @@ type Conn interface {
 	// Close closes the connection.
 	Close() error
 
-	// Err returns a non-nil value if the connection is broken. The returned
-	// value is either the first non-nil value returned from the underlying
-	// network connection or a protocol parsing error. Applications should
-	// close broken connections.
+	// Err returns a non-nil value when the connection is not usable.
 	Err() error
 
 	// Do sends a command to the server and returns the received reply.