Added a lot of documentation

query.go

@@ -6,8 +6,13 @@ import (
 	"time"
 )
 
+// Row is a convenience wrapper over Rows that is returned by QueryRow.
 type Row Rows
 
+// Scan reads the values from the row into dest values positionally. dest can
+// include pointers to core types and the Scanner interface. If no rows were
+// found it returns ErrNoRows. If multiple rows are returned it ignores all but
+// the first.
 func (r *Row) Scan(dest ...interface{}) (err error) {
 	rows := (*Rows)(r)
 
@@ -28,6 +33,9 @@ func (r *Row) Scan(dest ...interface{}) (err error) {
 	return rows.Err()
 }
 
+// Rows is the result set returned from *Conn.Query. Rows must be closed before
+// the *Conn can be used again. Rows are closed by explicitly calling Close(),
+// calling Next() until it returns false, or when a fatal error occurs.
 type Rows struct {
 	pool      *ConnPool
 	conn      *Conn
@@ -80,6 +88,10 @@ func (rows *Rows) readUntilReadyForQuery() {
 	}
 }
 
+// Close closes the rows, making the connection ready for use again. It is not
+// usually necessary to call Close explicitly because reading all returned rows
+// with Next automatically closes Rows. It is safe to call Close after rows is
+// already closed.
 func (rows *Rows) Close() {
 	if rows.closed {
 		return
@@ -103,7 +115,8 @@ func (rows *Rows) abort(err error) {
 	rows.close()
 }
 
-// Fatal signals an error occurred after the query was sent to the server
+// Fatal signals an error occurred after the query was sent to the server. It
+// closes the rows automatically.
 func (rows *Rows) Fatal(err error) {
 	if rows.err != nil {
 		return
@@ -113,6 +126,9 @@ func (rows *Rows) Fatal(err error) {
 	rows.Close()
 }
 
+// Next prepares the next row for reading. It returns true if there is another
+// row and false if no more rows are available. It automatically closes rows
+// when all rows are read.
 func (rows *Rows) Next() bool {
 	if rows.closed {
 		return false
@@ -170,6 +186,8 @@ func (rows *Rows) nextColumn() (*ValueReader, bool) {
 	return &rows.vr, true
 }
 
+// Scan reads the values from the current row into dest values positionally.
+// dest can include pointers to core types and the Scanner interface.
 func (rows *Rows) Scan(dest ...interface{}) (err error) {
 	if len(rows.fields) != len(dest) {
 		err = errors.New("Scan received wrong number of arguments")
@@ -177,7 +195,6 @@ func (rows *Rows) Scan(dest ...interface{}) (err error) {
 		return err
 	}
 
-	// TODO - decodeX should return err and Scan should Fatal the rows
 	for _, d := range dest {
 		vr, _ := rows.nextColumn()
 		switch d := d.(type) {
@@ -288,7 +305,9 @@ func (rows *Rows) Values() ([]interface{}, error) {
 	return values, rows.Err()
 }
 
-// TODO - document
+// Query executes sql with args. If there is an error the returned *Rows will
+// be returned in an error state. So it is allowed to ignore the error returned
+// from Query and handle it in *Rows.
 func (c *Conn) Query(sql string, args ...interface{}) (*Rows, error) {
 	c.rows = Rows{conn: c}
 	rows := &c.rows
@@ -331,6 +350,9 @@ func (c *Conn) Query(sql string, args ...interface{}) (*Rows, error) {
 	}
 }
 
+// QueryRow is a convenience wrapper over Query. Any error that occurs while
+// querying is deferred until calling Scan on the returned *Row. That *Row will
+// error with ErrNoRows if no rows are returned.
 func (c *Conn) QueryRow(sql string, args ...interface{}) *Row {
 	rows, _ := c.Query(sql, args...)
 	return (*Row)(rows)