Add golint, make it pass cleanly, fix some docs

This change introduces golint to the TravisCI build process, fixes
everything it has found, and additionally fixes some Godoc scrolling
isuues.

Fixes #669.

.travis.sh

@@ -85,4 +85,14 @@ megacheck_install() {
 	megacheck --version
 }
 
+golint_install() {
+	# Golint is Go 1.6+, so skip if Go 1.5.
+	if [[ "$(go version)" =~ "go1.5" ]]
+	then
+		echo "golint not supported, skipping installation"
+		return 0
+	fi
+	go get github.com/golang/lint/golint
+}
+
 $1

.travis.yml

@@ -34,6 +34,7 @@ before_install:
   - ./.travis.sh postgresql_configure
   - ./.travis.sh client_configure
   - ./.travis.sh megacheck_install
+  - ./.travis.sh golint_install
   - go get golang.org/x/tools/cmd/goimports
 
 before_script:
@@ -53,5 +54,7 @@ script:
     which megacheck > /dev/null
     && megacheck -ignore 'github.com/lib/pq/conn_test.go:SA1019 github.com/lib/pq/*.go:S1024' ./...
     || echo 'megacheck is not supported, skipping check'
+    # For compatibility with Go 1.5, launch only if golint is present.
+  - which golint > /dev/null && golint ./...  || echo 'golint is not supported, skipping check'
   - PQTEST_BINARY_PARAMETERS=no  go test -race -v ./...
   - PQTEST_BINARY_PARAMETERS=yes go test -race -v ./...

README.md

@@ -1,5 +1,6 @@
 # pq - A pure Go postgres driver for Go's database/sql package
 
+[![GoDoc](https://godoc.org/github.com/lib/pq?status.svg)](https://godoc.org/github.com/lib/pq)
 [![Build Status](https://travis-ci.org/lib/pq.svg?branch=master)](https://travis-ci.org/lib/pq)
 
 ## Install

conn.go

@@ -35,8 +35,12 @@ var (
 	errNoLastInsertID  = errors.New("no LastInsertId available after the empty statement")
 )
 
+// Driver is the Postgres database driver.
 type Driver struct{}
 
+// Open opens a new connection to the database. name is a connection string.
+// Most users should only use it through database/sql package from the standard
+// library.
 func (d *Driver) Open(name string) (driver.Conn, error) {
 	return Open(name)
 }
@@ -78,6 +82,8 @@ func (s transactionStatus) String() string {
 	panic("not reached")
 }
 
+// Dialer is the dialer interface. It can be used to obtain more control over
+// how pq creates network connections.
 type Dialer interface {
 	Dial(network, address string) (net.Conn, error)
 	DialTimeout(network, address string, timeout time.Duration) (net.Conn, error)
@@ -238,10 +244,14 @@ func (cn *conn) writeBuf(b byte) *writeBuf {
 	}
 }
 
+// Open opens a new connection to the database. name is a connection string.
+// Most users should only use it through database/sql package from the standard
+// library.
 func Open(name string) (_ driver.Conn, err error) {
 	return DialOpen(defaultDialer{}, name)
 }
 
+// DialOpen opens a new connection to the database using a dialer.
 func DialOpen(d Dialer, name string) (_ driver.Conn, err error) {
 	// Handle any panics during connection initialization.  Note that we
 	// specifically do *not* want to use errRecover(), as that would turn any
@@ -1432,7 +1442,8 @@ func (rs *rows) NextResultSet() error {
 //
 //    tblname := "my_table"
 //    data := "my_data"
-//    err = db.Exec(fmt.Sprintf("INSERT INTO %s VALUES ($1)", pq.QuoteIdentifier(tblname)), data)
+//    quoted := pq.QuoteIdentifier(tblname)
+//    err := db.Exec(fmt.Sprintf("INSERT INTO %s VALUES ($1)", quoted), data)
 //
 // Any double quotes in name will be escaped.  The quoted identifier will be
 // case sensitive when used in a query.  If the input string contains a zero

doc.go

@@ -11,7 +11,8 @@ using this package directly. For example:
 	)
 
 	func main() {
-		db, err := sql.Open("postgres", "user=pqgotest dbname=pqgotest sslmode=verify-full")
+		connStr := "user=pqgotest dbname=pqgotest sslmode=verify-full"
+		db, err := sql.Open("postgres", connStr)
 		if err != nil {
 			log.Fatal(err)
 		}
@@ -23,7 +24,8 @@ using this package directly. For example:
 
 You can also connect to a database using a URL. For example:
 
-	db, err := sql.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full")
+	connStr := "postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full"
+	db, err := sql.Open("postgres", connStr)
 
 
 Connection String Parameters
@@ -43,21 +45,28 @@ supported:
 	* dbname - The name of the database to connect to
 	* user - The user to sign in as
 	* password - The user's password
-	* host - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost)
+	* host - The host to connect to. Values that start with / are for unix
+	  domain sockets. (default is localhost)
 	* port - The port to bind to. (default is 5432)
-	* sslmode - Whether or not to use SSL (default is require, this is not the default for libpq)
+	* sslmode - Whether or not to use SSL (default is require, this is not
+	  the default for libpq)
 	* fallback_application_name - An application_name to fall back to if one isn't provided.
-	* connect_timeout - Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely.
+	* connect_timeout - Maximum wait for connection, in seconds. Zero or
+	  not specified means wait indefinitely.
 	* sslcert - Cert file location. The file must contain PEM encoded data.
 	* sslkey - Key file location. The file must contain PEM encoded data.
-	* sslrootcert - The location of the root certificate file. The file must contain PEM encoded data.
+	* sslrootcert - The location of the root certificate file. The file
+	  must contain PEM encoded data.
 
 Valid values for sslmode are:
 
 	* disable - No SSL
 	* require - Always SSL (skip verification)
-	* verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA)
-	* verify-full - Always SSL (verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate)
+	* verify-ca - Always SSL (verify that the certificate presented by the
+	  server was signed by a trusted CA)
+	* verify-full - Always SSL (verify that the certification presented by
+	  the server was signed by a trusted CA and the server host name
+	  matches the one in the certificate)
 
 See http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
 for more information about connection string parameters.
@@ -68,7 +77,7 @@ Use single quotes for values that contain whitespace:
 
 A backslash will escape the next character in values:
 
-    "user=space\ man password='it\'s valid'
+    "user=space\ man password='it\'s valid'"
 
 Note that the connection parameter client_encoding (which sets the
 text encoding for the connection) may be set but must be "UTF8",
@@ -129,7 +138,8 @@ This package returns the following types for values from the PostgreSQL backend:
 	- integer types smallint, integer, and bigint are returned as int64
 	- floating-point types real and double precision are returned as float64
 	- character types char, varchar, and text are returned as string
-	- temporal types date, time, timetz, timestamp, and timestamptz are returned as time.Time
+	- temporal types date, time, timetz, timestamp, and timestamptz are
+	  returned as time.Time
 	- the boolean type is returned as bool
 	- the bytea type is returned as []byte
 
@@ -229,7 +239,7 @@ for more information).  Note that the channel name will be truncated to 63
 bytes by the PostgreSQL server.
 
 You can find a complete, working example of Listener usage at
-http://godoc.org/github.com/lib/pq/listen_example.
+http://godoc.org/github.com/lib/pq/examples/listen.
 
 */
 package pq

listen_example/doc.go → example/listen/doc.go

@@ -1,6 +1,6 @@
 /*
 
-Below you will find a self-contained Go program which uses the LISTEN / NOTIFY
+Package listen is a self-contained Go program which uses the LISTEN / NOTIFY
 mechanism to avoid polling the database while waiting for more work to arrive.
 
     //
@@ -77,7 +77,9 @@ mechanism to avoid polling the database while waiting for more work to arrive.
             }
         }
 
-        listener := pq.NewListener(conninfo, 10 * time.Second, time.Minute, reportProblem)
+        minReconn := 10 * time.Second
+        maxReconn := time.Minute
+        listener := pq.NewListener(conninfo, minReconn, maxReconn, reportProblem)
         err = listener.Listen("getwork")
         if err != nil {
             panic(err)
@@ -93,4 +95,4 @@ mechanism to avoid polling the database while waiting for more work to arrive.
 
 
 */
-package listen_example
+package listen

hstore/hstore.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 )
 
-// A wrapper for transferring Hstore values back and forth easily.
+// Hstore is a wrapper for transferring Hstore values back and forth easily.
 type Hstore struct {
 	Map map[string]sql.NullString
 }

notify.go

@@ -60,7 +60,7 @@ type ListenerConn struct {
 	replyChan chan message
 }
 
-// Creates a new ListenerConn.  Use NewListener instead.
+// NewListenerConn creates a new ListenerConn. Use NewListener instead.
 func NewListenerConn(name string, notificationChan chan<- *Notification) (*ListenerConn, error) {
 	return newDialListenerConn(defaultDialer{}, name, notificationChan)
 }
@@ -214,17 +214,17 @@ func (l *ListenerConn) listenerConnMain() {
 	// this ListenerConn is done
 }
 
-// Send a LISTEN query to the server.  See ExecSimpleQuery.
+// Listen sends a LISTEN query to the server. See ExecSimpleQuery.
 func (l *ListenerConn) Listen(channel string) (bool, error) {
 	return l.ExecSimpleQuery("LISTEN " + QuoteIdentifier(channel))
 }
 
-// Send an UNLISTEN query to the server.  See ExecSimpleQuery.
+// Unlisten sends an UNLISTEN query to the server. See ExecSimpleQuery.
 func (l *ListenerConn) Unlisten(channel string) (bool, error) {
 	return l.ExecSimpleQuery("UNLISTEN " + QuoteIdentifier(channel))
 }
 
-// Send `UNLISTEN *` to the server.  See ExecSimpleQuery.
+// UnlistenAll sends an `UNLISTEN *` query to the server. See ExecSimpleQuery.
 func (l *ListenerConn) UnlistenAll() (bool, error) {
 	return l.ExecSimpleQuery("UNLISTEN *")
 }
@@ -267,8 +267,8 @@ func (l *ListenerConn) sendSimpleQuery(q string) (err error) {
 	return nil
 }
 
-// Execute a "simple query" (i.e. one with no bindable parameters) on the
-// connection.  The possible return values are:
+// ExecSimpleQuery executes a "simple query" (i.e. one with no bindable
+// parameters) on the connection. The possible return values are:
 //   1) "executed" is true; the query was executed to completion on the
 //      database server.  If the query failed, err will be set to the error
 //      returned by the database, otherwise err will be nil.
@@ -333,6 +333,7 @@ func (l *ListenerConn) ExecSimpleQuery(q string) (executed bool, err error) {
 	}
 }
 
+// Close closes the connection.
 func (l *ListenerConn) Close() error {
 	l.connectionLock.Lock()
 	if l.err != nil {
@@ -346,40 +347,51 @@ func (l *ListenerConn) Close() error {
 	return l.cn.c.Close()
 }
 
-// Err() returns the reason the connection was closed.  It is not safe to call
+// Err returns the reason the connection was closed. It is not safe to call
 // this function until l.Notify has been closed.
 func (l *ListenerConn) Err() error {
 	return l.err
 }
 
 var errListenerClosed = errors.New("pq: Listener has been closed")
 
+// ErrChannelAlreadyOpen is returned from Listen when a channel is already
+// open.
 var ErrChannelAlreadyOpen = errors.New("pq: channel is already open")
+
+// ErrChannelNotOpen is returned from Unlisten when a channel is not open.
 var ErrChannelNotOpen = errors.New("pq: channel is not open")
 
+// ListenerEventType is an enumeration of listener event types.
 type ListenerEventType int
 
 const (
-	// Emitted only when the database connection has been initially
-	// initialized.  err will always be nil.
+	// ListenerEventConnected is emitted only when the database connection
+	// has been initially initialized. The err argument of the callback
+	// will always be nil.
 	ListenerEventConnected ListenerEventType = iota
 
-	// Emitted after a database connection has been lost, either because of an
-	// error or because Close has been called.  err will be set to the reason
-	// the database connection was lost.
+	// ListenerEventDisconnected is emitted after a database connection has
+	// been lost, either because of an error or because Close has been
+	// called. The err argument will be set to the reason the database
+	// connection was lost.
 	ListenerEventDisconnected
 
-	// Emitted after a database connection has been re-established after
-	// connection loss.  err will always be nil.  After this event has been
-	// emitted, a nil pq.Notification is sent on the Listener.Notify channel.
+	// ListenerEventReconnected is emitted after a database connection has
+	// been re-established after connection loss. The err argument of the
+	// callback will always be nil. After this event has been emitted, a
+	// nil pq.Notification is sent on the Listener.Notify channel.
 	ListenerEventReconnected
 
-	// Emitted after a connection to the database was attempted, but failed.
-	// err will be set to an error describing why the connection attempt did
-	// not succeed.
+	// ListenerEventConnectionAttemptFailed is emitted after a connection
+	// to the database was attempted, but failed. The err argument will be
+	// set to an error describing why the connection attempt did not
+	// succeed.
 	ListenerEventConnectionAttemptFailed
 )
 
+// EventCallbackType is the event callback type. See also ListenerEventType
+// constants' documentation.
 type EventCallbackType func(event ListenerEventType, err error)
 
 // Listener provides an interface for listening to notifications from a
@@ -454,9 +466,9 @@ func NewDialListener(d Dialer,
 	return l
 }
 
-// Returns the notification channel for this listener.  This is the same
-// channel as Notify, and will not be recreated during the life time of the
-// Listener.
+// NotificationChannel returns the notification channel for this listener.
+// This is the same channel as Notify, and will not be recreated during the
+// life time of the Listener.
 func (l *Listener) NotificationChannel() <-chan *Notification {
 	return l.Notify
 }