database/sql: document closing requirements for Stmts

Fixes #8952.

Change-Id: I678f9706eccb5a344eeb0244f45b7b7669830bdc
Reviewed-on: https://go-review.googlesource.com/12204
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 17afa4966b71e89eec218653093d61fb6c697d1d..aaa4ea28be4527d956e58c08a9d103c2ac7ac42a 100644 (file)
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -840,6 +840,8 @@ const maxBadConnRetries = 2
 // Prepare creates a prepared statement for later queries or executions.
 // Multiple queries or executions may be run concurrently from the
 // returned statement.
+// The caller must call the statement's Close method
+// when the statement is no longer needed.
 func (db *DB) Prepare(query string) (*Stmt, error) {
        var stmt *Stmt
        var err error
@@ -1074,6 +1076,10 @@ func (db *DB) Driver() driver.Driver {
 //
 // After a call to Commit or Rollback, all operations on the
 // transaction fail with ErrTxDone.
+//
+// The statements prepared for a transaction by calling
+// the transaction's Prepare or Stmt methods are closed
+// by the call to Commit or Rollback.
 type Tx struct {
        db *DB
 
@@ -1209,6 +1215,9 @@ func (tx *Tx) Prepare(query string) (*Stmt, error) {
 //  tx, err := db.Begin()
 //  ...
 //  res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
+//
+// The returned statement operates within the transaction and can no longer
+// be used once the transaction has been committed or rolled back.
 func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
        // TODO(bradfitz): optimize this. Currently this re-prepares
        // each time.  This is fine for now to illustrate the API but
@@ -1300,7 +1309,8 @@ type connStmt struct {
        si driver.Stmt
 }
 
-// Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
+// Stmt is a prepared statement.
+// A Stmt is safe for concurrent use by multiple goroutines.
 type Stmt struct {
        // Immutable:
        db        *DB    // where we came from