database: add available godoc link

Change-Id: I6150858f1186edc6cebd38ff166d57287fa430f9
Reviewed-on: https://go-review.googlesource.com/c/go/+/535078
Reviewed-by: Carlos Amedee <carlos@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: shuang cui <imcusg@gmail.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Auto-Submit: Ian Lance Taylor <iant@google.com>

1 files changed, 154 insertions, 154 deletions

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 013c03d97a..e70aa8b550 100644
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -77,7 +77,7 @@ func Drivers() []string {
 // parameter in the SQL statement.
 //
 // For a more concise way to create NamedArg values, see
-// the Named function.
+// the [Named] function.
 type NamedArg struct {
 	_NamedFieldsRequired struct{}
 
@@ -95,7 +95,7 @@ type NamedArg struct {
 	Value any
 }
 
-// Named provides a more concise way to create NamedArg values.
+// Named provides a more concise way to create [NamedArg] values.
 //
 // Example usage:
 //
@@ -115,7 +115,7 @@ func Named(name string, value any) NamedArg {
 	return NamedArg{Name: name, Value: value}
 }
 
-// IsolationLevel is the transaction isolation level used in TxOptions.
+// IsolationLevel is the transaction isolation level used in [TxOptions].
 type IsolationLevel int
 
 // Various isolation levels that drivers may support in BeginTx.
@@ -159,7 +159,7 @@ func (i IsolationLevel) String() string {
 
 var _ fmt.Stringer = LevelDefault
 
-// TxOptions holds the transaction options to be used in DB.BeginTx.
+// TxOptions holds the transaction options to be used in [DB.BeginTx].
 type TxOptions struct {
 	// Isolation is the transaction isolation level.
 	// If zero, the driver or database's default level is used.
@@ -173,7 +173,7 @@ type TxOptions struct {
 type RawBytes []byte
 
 // NullString represents a string that may be null.
-// NullString implements the Scanner interface so
+// NullString implements the [Scanner] interface so
 // it can be used as a scan destination:
 //
 //	var s NullString
@@ -189,7 +189,7 @@ type NullString struct {
 	Valid  bool // Valid is true if String is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (ns *NullString) Scan(value any) error {
 	if value == nil {
 		ns.String, ns.Valid = "", false
@@ -199,7 +199,7 @@ func (ns *NullString) Scan(value any) error {
 	return convertAssign(&ns.String, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (ns NullString) Value() (driver.Value, error) {
 	if !ns.Valid {
 		return nil, nil
@@ -208,14 +208,14 @@ func (ns NullString) Value() (driver.Value, error) {
 }
 
 // NullInt64 represents an int64 that may be null.
-// NullInt64 implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullInt64 implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullInt64 struct {
 	Int64 int64
 	Valid bool // Valid is true if Int64 is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullInt64) Scan(value any) error {
 	if value == nil {
 		n.Int64, n.Valid = 0, false
@@ -225,7 +225,7 @@ func (n *NullInt64) Scan(value any) error {
 	return convertAssign(&n.Int64, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullInt64) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -234,14 +234,14 @@ func (n NullInt64) Value() (driver.Value, error) {
 }
 
 // NullInt32 represents an int32 that may be null.
-// NullInt32 implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullInt32 implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullInt32 struct {
 	Int32 int32
 	Valid bool // Valid is true if Int32 is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullInt32) Scan(value any) error {
 	if value == nil {
 		n.Int32, n.Valid = 0, false
@@ -251,7 +251,7 @@ func (n *NullInt32) Scan(value any) error {
 	return convertAssign(&n.Int32, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullInt32) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -260,14 +260,14 @@ func (n NullInt32) Value() (driver.Value, error) {
 }
 
 // NullInt16 represents an int16 that may be null.
-// NullInt16 implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullInt16 implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullInt16 struct {
 	Int16 int16
 	Valid bool // Valid is true if Int16 is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullInt16) Scan(value any) error {
 	if value == nil {
 		n.Int16, n.Valid = 0, false
@@ -278,7 +278,7 @@ func (n *NullInt16) Scan(value any) error {
 	return err
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullInt16) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -287,14 +287,14 @@ func (n NullInt16) Value() (driver.Value, error) {
 }
 
 // NullByte represents a byte that may be null.
-// NullByte implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullByte implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullByte struct {
 	Byte  byte
 	Valid bool // Valid is true if Byte is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullByte) Scan(value any) error {
 	if value == nil {
 		n.Byte, n.Valid = 0, false
@@ -305,7 +305,7 @@ func (n *NullByte) Scan(value any) error {
 	return err
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullByte) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -314,14 +314,14 @@ func (n NullByte) Value() (driver.Value, error) {
 }
 
 // NullFloat64 represents a float64 that may be null.
-// NullFloat64 implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullFloat64 implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullFloat64 struct {
 	Float64 float64
 	Valid   bool // Valid is true if Float64 is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullFloat64) Scan(value any) error {
 	if value == nil {
 		n.Float64, n.Valid = 0, false
@@ -331,7 +331,7 @@ func (n *NullFloat64) Scan(value any) error {
 	return convertAssign(&n.Float64, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullFloat64) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -340,14 +340,14 @@ func (n NullFloat64) Value() (driver.Value, error) {
 }
 
 // NullBool represents a bool that may be null.
-// NullBool implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullBool implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullBool struct {
 	Bool  bool
 	Valid bool // Valid is true if Bool is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullBool) Scan(value any) error {
 	if value == nil {
 		n.Bool, n.Valid = false, false
@@ -357,7 +357,7 @@ func (n *NullBool) Scan(value any) error {
 	return convertAssign(&n.Bool, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullBool) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -365,15 +365,15 @@ func (n NullBool) Value() (driver.Value, error) {
 	return n.Bool, nil
 }
 
-// NullTime represents a time.Time that may be null.
-// NullTime implements the Scanner interface so
-// it can be used as a scan destination, similar to NullString.
+// NullTime represents a [time.Time] that may be null.
+// NullTime implements the [Scanner] interface so
+// it can be used as a scan destination, similar to [NullString].
 type NullTime struct {
 	Time  time.Time
 	Valid bool // Valid is true if Time is not NULL
 }
 
-// Scan implements the Scanner interface.
+// Scan implements the [Scanner] interface.
 func (n *NullTime) Scan(value any) error {
 	if value == nil {
 		n.Time, n.Valid = time.Time{}, false
@@ -383,7 +383,7 @@ func (n *NullTime) Scan(value any) error {
 	return convertAssign(&n.Time, value)
 }
 
-// Value implements the driver Valuer interface.
+// Value implements the [driver.Valuer] interface.
 func (n NullTime) Value() (driver.Value, error) {
 	if !n.Valid {
 		return nil, nil
@@ -392,7 +392,7 @@ func (n NullTime) Value() (driver.Value, error) {
 }
 
 // Null represents a value that may be null.
-// Null implements the Scanner interface so
+// Null implements the [Scanner] interface so
 // it can be used as a scan destination:
 //
 //	var s Null[string]
@@ -424,7 +424,7 @@ func (n Null[T]) Value() (driver.Value, error) {
 	return n.V, nil
 }
 
-// Scanner is an interface used by Scan.
+// Scanner is an interface used by [Scan].
 type Scanner interface {
 	// Scan assigns a value from a database driver.
 	//
@@ -469,7 +469,7 @@ type Out struct {
 }
 
 // ErrNoRows is returned by Scan when QueryRow doesn't return a
-// row. In such a case, QueryRow returns a placeholder *Row value that
+// row. In such a case, QueryRow returns a placeholder *[Row] value that
 // defers this error until a Scan.
 var ErrNoRows = errors.New("sql: no rows in result set")
 
@@ -480,10 +480,10 @@ var ErrNoRows = errors.New("sql: no rows in result set")
 // The sql package creates and frees connections automatically; it
 // also maintains a free pool of idle connections. If the database has
 // a concept of per-connection state, such state can be reliably observed
-// within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the
-// returned Tx is bound to a single connection. Once Commit or
+// within a transaction ([Tx]) or connection ([Conn]). Once [DB.Begin] is called, the
+// returned [Tx] is bound to a single connection. Once Commit or
 // Rollback is called on the transaction, that transaction's
-// connection is returned to DB's idle connection pool. The pool size
+// connection is returned to [DB]'s idle connection pool. The pool size
 // can be controlled with SetMaxIdleConns.
 type DB struct {
 	// Total time waited for new connections.
@@ -799,7 +799,7 @@ func (t dsnConnector) Driver() driver.Driver {
 // bypass a string based data source name.
 //
 // Most users will open a database via a driver-specific connection
-// helper function that returns a *DB. No database drivers are included
+// helper function that returns a *[DB]. No database drivers are included
 // in the Go standard library. See https://golang.org/s/sqldrivers for
 // a list of third-party drivers.
 //
@@ -807,10 +807,10 @@ func (t dsnConnector) Driver() driver.Driver {
 // to the database. To verify that the data source name is valid, call
 // Ping.
 //
-// The returned DB is safe for concurrent use by multiple goroutines
+// The returned [DB] is safe for concurrent use by multiple goroutines
 // and maintains its own pool of idle connections. Thus, the OpenDB
 // function should be called just once. It is rarely necessary to
-// close a DB.
+// close a [DB].
 func OpenDB(c driver.Connector) *DB {
 	ctx, cancel := context.WithCancel(context.Background())
 	db := &DB{
@@ -831,7 +831,7 @@ func OpenDB(c driver.Connector) *DB {
 // database name and connection information.
 //
 // Most users will open a database via a driver-specific connection
-// helper function that returns a *DB. No database drivers are included
+// helper function that returns a *[DB]. No database drivers are included
 // in the Go standard library. See https://golang.org/s/sqldrivers for
 // a list of third-party drivers.
 //
@@ -839,10 +839,10 @@ func OpenDB(c driver.Connector) *DB {
 // to the database. To verify that the data source name is valid, call
 // Ping.
 //
-// The returned DB is safe for concurrent use by multiple goroutines
+// The returned [DB] is safe for concurrent use by multiple goroutines
 // and maintains its own pool of idle connections. Thus, the Open
 // function should be called just once. It is rarely necessary to
-// close a DB.
+// close a [DB].
 func Open(driverName, dataSourceName string) (*DB, error) {
 	driversMu.RLock()
 	driveri, ok := drivers[driverName]
@@ -894,8 +894,8 @@ func (db *DB) PingContext(ctx context.Context) error {
 // Ping verifies a connection to the database is still alive,
 // establishing a connection if necessary.
 //
-// Ping uses context.Background internally; to specify the context, use
-// PingContext.
+// Ping uses [context.Background] internally; to specify the context, use
+// [PingContext].
 func (db *DB) Ping() error {
 	return db.PingContext(context.Background())
 }
@@ -904,7 +904,7 @@ func (db *DB) Ping() error {
 // Close then waits for all queries that have started processing on the server
 // to finish.
 //
-// It is rare to Close a DB, as the DB handle is meant to be
+// It is rare to Close a [DB], as the [DB] handle is meant to be
 // long-lived and shared between many goroutines.
 func (db *DB) Close() error {
 	db.mu.Lock()
@@ -1576,7 +1576,7 @@ func (db *DB) retry(fn func(strategy connReuseStrategy) error) error {
 // PrepareContext 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
+// The caller must call the statement's [DB.Close] method
 // when the statement is no longer needed.
 //
 // The provided context is used for the preparation of the statement, not for the
@@ -1599,8 +1599,8 @@ func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
 // The caller must call the statement's Close method
 // when the statement is no longer needed.
 //
-// Prepare uses context.Background internally; to specify the context, use
-// PrepareContext.
+// Prepare uses [context.Background] internally; to specify the context, use
+// [DB.PrepareContext].
 func (db *DB) Prepare(query string) (*Stmt, error) {
 	return db.PrepareContext(context.Background(), query)
 }
@@ -1669,8 +1669,8 @@ func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Resul
 // Exec executes a query without returning any rows.
 // The args are for any placeholder parameters in the query.
 //
-// Exec uses context.Background internally; to specify the context, use
-// ExecContext.
+// Exec uses [context.Background] internally; to specify the context, use
+// [DB.ExecContext].
 func (db *DB) Exec(query string, args ...any) (Result, error) {
 	return db.ExecContext(context.Background(), query, args...)
 }
@@ -1739,8 +1739,8 @@ func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Row
 // Query executes a query that returns rows, typically a SELECT.
 // The args are for any placeholder parameters in the query.
 //
-// Query uses context.Background internally; to specify the context, use
-// QueryContext.
+// Query uses [context.Background] internally; to specify the context, use
+// [DB.QueryContext].
 func (db *DB) Query(query string, args ...any) (*Rows, error) {
 	return db.QueryContext(context.Background(), query, args...)
 }
@@ -1824,9 +1824,9 @@ func (db *DB) queryDC(ctx, txctx context.Context, dc *driverConn, releaseConn fu
 
 // QueryRowContext executes a query that is expected to return at most one row.
 // QueryRowContext always returns a non-nil value. Errors are deferred until
-// Row's Scan method is called.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// [Row]'s Scan method is called.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
 	rows, err := db.QueryContext(ctx, query, args...)
@@ -1835,13 +1835,13 @@ func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *R
 
 // QueryRow executes a query that is expected to return at most one row.
 // QueryRow always returns a non-nil value. Errors are deferred until
-// Row's Scan method is called.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// [Row]'s Scan method is called.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 //
-// QueryRow uses context.Background internally; to specify the context, use
-// QueryRowContext.
+// QueryRow uses [context.Background] internally; to specify the context, use
+// [DB.QueryRowContext].
 func (db *DB) QueryRow(query string, args ...any) *Row {
 	return db.QueryRowContext(context.Background(), query, args...)
 }
@@ -1850,10 +1850,10 @@ func (db *DB) QueryRow(query string, args ...any) *Row {
 //
 // The provided context is used until the transaction is committed or rolled back.
 // If the context is canceled, the sql package will roll back
-// the transaction. Tx.Commit will return an error if the context provided to
+// the transaction. [Tx.Commit] will return an error if the context provided to
 // BeginTx is canceled.
 //
-// The provided TxOptions is optional and may be nil if defaults should be used.
+// The provided [TxOptions] is optional and may be nil if defaults should be used.
 // If a non-default isolation level is used that the driver doesn't support,
 // an error will be returned.
 func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
@@ -1871,8 +1871,8 @@ func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
 // Begin starts a transaction. The default isolation level is dependent on
 // the driver.
 //
-// Begin uses context.Background internally; to specify the context, use
-// BeginTx.
+// Begin uses [context.Background] internally; to specify the context, use
+// [DB.BeginTx].
 func (db *DB) Begin() (*Tx, error) {
 	return db.BeginTx(context.Background(), nil)
 }
@@ -1931,7 +1931,7 @@ var ErrConnDone = errors.New("sql: connection is already closed")
 // Queries run on the same Conn will be run in the same database session.
 //
 // Every Conn must be returned to the database pool after use by
-// calling Conn.Close.
+// calling [Conn.Close].
 func (db *DB) Conn(ctx context.Context) (*Conn, error) {
 	var dc *driverConn
 	var err error
@@ -1955,14 +1955,14 @@ func (db *DB) Conn(ctx context.Context) (*Conn, error) {
 type releaseConn func(error)
 
 // Conn represents a single database connection rather than a pool of database
-// connections. Prefer running queries from DB unless there is a specific
+// connections. Prefer running queries from [DB] unless there is a specific
 // need for a continuous single database connection.
 //
-// A Conn must call Close to return the connection to the database pool
+// A Conn must call [Conn.Close] to return the connection to the database pool
 // and may do so concurrently with a running query.
 //
-// After a call to Close, all operations on the
-// connection fail with ErrConnDone.
+// After a call to [Conn.Close], all operations on the
+// connection fail with [ErrConnDone].
 type Conn struct {
 	db *DB
 
@@ -2029,9 +2029,9 @@ func (c *Conn) QueryContext(ctx context.Context, query string, args ...any) (*Ro
 
 // QueryRowContext executes a query that is expected to return at most one row.
 // QueryRowContext always returns a non-nil value. Errors are deferred until
-// Row's Scan method is called.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// [Row]'s Scan method is called.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
 	rows, err := c.QueryContext(ctx, query, args...)
@@ -2041,7 +2041,7 @@ func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *
 // PrepareContext 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
+// The caller must call the statement's [Conn.Close] method
 // when the statement is no longer needed.
 //
 // The provided context is used for the preparation of the statement, not for the
@@ -2057,8 +2057,8 @@ func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error)
 // Raw executes f exposing the underlying driver connection for the
 // duration of f. The driverConn must not be used outside of f.
 //
-// Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable
-// until Conn.Close is called.
+// Once f returns and err is not driver.ErrBadConn, the [Conn] will continue to be usable
+// until [Conn.Close] is called.
 func (c *Conn) Raw(f func(driverConn any) error) (err error) {
 	var dc *driverConn
 	var release releaseConn
@@ -2091,10 +2091,10 @@ func (c *Conn) Raw(f func(driverConn any) error) (err error) {
 //
 // The provided context is used until the transaction is committed or rolled back.
 // If the context is canceled, the sql package will roll back
-// the transaction. Tx.Commit will return an error if the context provided to
+// the transaction. [Tx.Commit] will return an error if the context provided to
 // BeginTx is canceled.
 //
-// The provided TxOptions is optional and may be nil if defaults should be used.
+// The provided [TxOptions] is optional and may be nil if defaults should be used.
 // If a non-default isolation level is used that the driver doesn't support,
 // an error will be returned.
 func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
@@ -2135,7 +2135,7 @@ func (c *Conn) close(err error) error {
 }
 
 // Close returns the connection to the connection pool.
-// All operations after a Close will return with ErrConnDone.
+// All operations after a Close will return with [ErrConnDone].
 // Close is safe to call concurrently with other operations and will
 // block until all other operations finish. It may be useful to first
 // cancel any used context and then call close directly after.
@@ -2145,14 +2145,14 @@ func (c *Conn) Close() error {
 
 // Tx is an in-progress database transaction.
 //
-// A transaction must end with a call to Commit or Rollback.
+// A transaction must end with a call to [Tx.Commit] or [Tx.Rollback].
 //
-// After a call to Commit or Rollback, all operations on the
-// transaction fail with ErrTxDone.
+// After a call to [Tx.Commit] or [Tx.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.
+// the transaction's [Tx.Prepare] or [Tx.Stmt] methods are closed
+// by the call to [Tx.Commit] or [Tx.Rollback].
 type Tx struct {
 	db *DB
 
@@ -2354,7 +2354,7 @@ func (tx *Tx) Rollback() error {
 // The returned statement operates within the transaction and will be closed
 // when the transaction has been committed or rolled back.
 //
-// To use an existing prepared statement on this transaction, see Tx.Stmt.
+// To use an existing prepared statement on this transaction, see [Tx.Stmt].
 //
 // The provided context will be used for the preparation of the context, not
 // for the execution of the returned statement. The returned statement
@@ -2380,10 +2380,10 @@ func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
 // The returned statement operates within the transaction and will be closed
 // when the transaction has been committed or rolled back.
 //
-// To use an existing prepared statement on this transaction, see Tx.Stmt.
+// To use an existing prepared statement on this transaction, see [Tx.Stmt].
 //
-// Prepare uses context.Background internally; to specify the context, use
-// PrepareContext.
+// Prepare uses [context.Background] internally; to specify the context, use
+// [Tx.PrepareContext].
 func (tx *Tx) Prepare(query string) (*Stmt, error) {
 	return tx.PrepareContext(context.Background(), query)
 }
@@ -2490,8 +2490,8 @@ func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt {
 // The returned statement operates within the transaction and will be closed
 // when the transaction has been committed or rolled back.
 //
-// Stmt uses context.Background internally; to specify the context, use
-// StmtContext.
+// Stmt uses [context.Background] internally; to specify the context, use
+// [Tx.StmtContext].
 func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
 	return tx.StmtContext(context.Background(), stmt)
 }
@@ -2509,8 +2509,8 @@ func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (Resul
 // Exec executes a query that doesn't return rows.
 // For example: an INSERT and UPDATE.
 //
-// Exec uses context.Background internally; to specify the context, use
-// ExecContext.
+// Exec uses [context.Background] internally; to specify the context, use
+// [Tx.ExecContext].
 func (tx *Tx) Exec(query string, args ...any) (Result, error) {
 	return tx.ExecContext(context.Background(), query, args...)
 }
@@ -2527,17 +2527,17 @@ func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Row
 
 // Query executes a query that returns rows, typically a SELECT.
 //
-// Query uses context.Background internally; to specify the context, use
-// QueryContext.
+// Query uses [context.Background] internally; to specify the context, use
+// [Tx.QueryContext].
 func (tx *Tx) Query(query string, args ...any) (*Rows, error) {
 	return tx.QueryContext(context.Background(), query, args...)
 }
 
 // QueryRowContext executes a query that is expected to return at most one row.
 // QueryRowContext always returns a non-nil value. Errors are deferred until
-// Row's Scan method is called.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// [Row]'s Scan method is called.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
 	rows, err := tx.QueryContext(ctx, query, args...)
@@ -2546,13 +2546,13 @@ func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *R
 
 // QueryRow executes a query that is expected to return at most one row.
 // QueryRow always returns a non-nil value. Errors are deferred until
-// Row's Scan method is called.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// [Row]'s Scan method is called.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 //
-// QueryRow uses context.Background internally; to specify the context, use
-// QueryRowContext.
+// QueryRow uses [context.Background] internally; to specify the context, use
+// [Tx.QueryRowContext].
 func (tx *Tx) QueryRow(query string, args ...any) *Row {
 	return tx.QueryRowContext(context.Background(), query, args...)
 }
@@ -2584,11 +2584,11 @@ var (
 // Stmt is a prepared statement.
 // A Stmt is safe for concurrent use by multiple goroutines.
 //
-// If a Stmt is prepared on a Tx or Conn, it will be bound to a single
-// underlying connection forever. If the Tx or Conn closes, the Stmt will
+// If a Stmt is prepared on a [Tx] or [Conn], it will be bound to a single
+// underlying connection forever. If the [Tx] or [Conn] closes, the Stmt will
 // become unusable and all operations will return an error.
-// If a Stmt is prepared on a DB, it will remain usable for the lifetime of the
-// DB. When the Stmt needs to execute on a new underlying connection, it will
+// If a Stmt is prepared on a [DB], it will remain usable for the lifetime of the
+// [DB]. When the Stmt needs to execute on a new underlying connection, it will
 // prepare itself on the new connection automatically.
 type Stmt struct {
 	// Immutable:
@@ -2629,7 +2629,7 @@ type Stmt struct {
 }
 
 // ExecContext executes a prepared statement with the given arguments and
-// returns a Result summarizing the effect of the statement.
+// returns a [Result] summarizing the effect of the statement.
 func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error) {
 	s.closemu.RLock()
 	defer s.closemu.RUnlock()
@@ -2650,10 +2650,10 @@ func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error) {
 }
 
 // Exec executes a prepared statement with the given arguments and
-// returns a Result summarizing the effect of the statement.
+// returns a [Result] summarizing the effect of the statement.
 //
-// Exec uses context.Background internally; to specify the context, use
-// ExecContext.
+// Exec uses [context.Background] internally; to specify the context, use
+// [Stmt.ExecContext].
 func (s *Stmt) Exec(args ...any) (Result, error) {
 	return s.ExecContext(context.Background(), args...)
 }
@@ -2769,7 +2769,7 @@ func (s *Stmt) prepareOnConnLocked(ctx context.Context, dc *driverConn) (*driver
 }
 
 // QueryContext executes a prepared query statement with the given arguments
-// and returns the query results as a *Rows.
+// and returns the query results as a *[Rows].
 func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error) {
 	s.closemu.RLock()
 	defer s.closemu.RUnlock()
@@ -2820,8 +2820,8 @@ func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error) {
 // Query executes a prepared query statement with the given arguments
 // and returns the query results as a *Rows.
 //
-// Query uses context.Background internally; to specify the context, use
-// QueryContext.
+// Query uses [context.Background] internally; to specify the context, use
+// [Stmt.QueryContext].
 func (s *Stmt) Query(args ...any) (*Rows, error) {
 	return s.QueryContext(context.Background(), args...)
 }
@@ -2838,9 +2838,9 @@ func rowsiFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, arg
 
 // QueryRowContext executes a prepared query statement with the given arguments.
 // If an error occurs during the execution of the statement, that error will
-// be returned by a call to Scan on the returned *Row, which is always non-nil.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// be returned by a call to Scan on the returned *[Row], which is always non-nil.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row {
 	rows, err := s.QueryContext(ctx, args...)
@@ -2852,9 +2852,9 @@ func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row {
 
 // QueryRow executes a prepared query statement with the given arguments.
 // If an error occurs during the execution of the statement, that error will
-// be returned by a call to Scan on the returned *Row, which is always non-nil.
-// If the query selects no rows, the *Row's Scan will return ErrNoRows.
-// Otherwise, the *Row's Scan scans the first selected row and discards
+// be returned by a call to Scan on the returned *[Row], which is always non-nil.
+// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// Otherwise, the *[Row]'s Scan scans the first selected row and discards
 // the rest.
 //
 // Example usage:
@@ -2862,8 +2862,8 @@ func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row {
 //	var name string
 //	err := nameByUseridStmt.QueryRow(id).Scan(&name)
 //
-// QueryRow uses context.Background internally; to specify the context, use
-// QueryRowContext.
+// QueryRow uses [context.Background] internally; to specify the context, use
+// [Stmt.QueryRowContext].
 func (s *Stmt) QueryRow(args ...any) *Row {
 	return s.QueryRowContext(context.Background(), args...)
 }
@@ -2913,7 +2913,7 @@ func (s *Stmt) finalClose() error {
 }
 
 // Rows is the result of a query. Its cursor starts before the first row
-// of the result set. Use Next to advance from row to row.
+// of the result set. Use [Rows.Next] to advance from row to row.
 type Rows struct {
 	dc          *driverConn // owned; must call releaseConn when closed to release
 	releaseConn func(error)
@@ -3001,12 +3001,12 @@ func (rs *Rows) awaitDone(ctx, txctx, closectx context.Context) {
 	rs.close(ctx.Err())
 }
 
-// Next prepares the next result row for reading with the Scan method. It
+// Next prepares the next result row for reading with the [Rows.Scan] method. It
 // returns true on success, or false if there is no next result row or an error
-// happened while preparing it. Err should be consulted to distinguish between
+// happened while preparing it. [Rows.Err] should be consulted to distinguish between
 // the two cases.
 //
-// Every call to Scan, even the first one, must be preceded by a call to Next.
+// Every call to [Rows.Scan], even the first one, must be preceded by a call to [Rows.Next].
 func (rs *Rows) Next() bool {
 	// If the user's calling Next, they're done with their previous row's Scan
 	// results (any RawBytes memory), so we can release the read lock that would
@@ -3067,10 +3067,10 @@ func (rs *Rows) nextLocked() (doClose, ok bool) {
 
 // NextResultSet prepares the next result set for reading. It reports whether
 // there is further result sets, or false if there is no further result set
-// or if there is an error advancing to it. The Err method should be consulted
+// or if there is an error advancing to it. The [Rows.Err] method should be consulted
 // to distinguish between the two cases.
 //
-// After calling NextResultSet, the Next method should always be called before
+// After calling NextResultSet, the [Rows.Next] method should always be called before
 // scanning. If there are further result sets they may not have rows in the result
 // set.
 func (rs *Rows) NextResultSet() bool {
@@ -3113,7 +3113,7 @@ func (rs *Rows) NextResultSet() bool {
 }
 
 // Err returns the error, if any, that was encountered during iteration.
-// Err may be called after an explicit or implicit Close.
+// Err may be called after an explicit or implicit [Rows.Close].
 func (rs *Rows) Err() error {
 	// Return any context error that might've happened during row iteration,
 	// but only if we haven't reported the final Next() = false after rows
@@ -3190,7 +3190,7 @@ func (ci *ColumnType) Name() string {
 
 // Length returns the column type length for variable length column types such
 // as text and binary field types. If the type length is unbounded the value will
-// be math.MaxInt64 (any database limits will still apply).
+// be [math.MaxInt64] (any database limits will still apply).
 // If the column type is not variable length, such as an int, or if not supported
 // by the driver ok is false.
 func (ci *ColumnType) Length() (length int64, ok bool) {
@@ -3203,7 +3203,7 @@ func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool) {
 	return ci.precision, ci.scale, ci.hasPrecisionScale
 }
 
-// ScanType returns a Go type suitable for scanning into using Rows.Scan.
+// ScanType returns a Go type suitable for scanning into using [Rows.Scan].
 // If a driver does not support this property ScanType will return
 // the type of an empty interface.
 func (ci *ColumnType) ScanType() reflect.Type {
@@ -3218,7 +3218,7 @@ func (ci *ColumnType) Nullable() (nullable, ok bool) {
 
 // DatabaseTypeName returns the database system name of the column type. If an empty
 // string is returned, then the driver type name is not supported.
-// Consult your driver documentation for a list of driver data types. Length specifiers
+// Consult your driver documentation for a list of driver data types. [ColumnType.Length] specifiers
 // are not included.
 // Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL",
 // "INT", and "BIGINT".
@@ -3259,7 +3259,7 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 
 // Scan copies the columns in the current row into the values pointed
 // at by dest. The number of values in dest must be the same as the
-// number of columns in Rows.
+// number of columns in [Rows].
 //
 // Scan converts columns read from the database into the following
 // common Go types and special types provided by the sql package:
@@ -3271,9 +3271,9 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 //	*bool
 //	*float32, *float64
 //	*interface{}
-//	*RawBytes
-//	*Rows (cursor value)
-//	any type implementing Scanner (see Scanner docs)
+//	*[RawBytes]
+//	*[Rows] (cursor value)
+//	any type implementing [Scanner] (see Scanner docs)
 //
 // In the most simple case, if the type of the value from the source
 // column is an integer, bool or string type T and dest is of type *T,
@@ -3292,8 +3292,8 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 // If a dest argument has type *[]byte, Scan saves in that argument a
 // copy of the corresponding data. The copy is owned by the caller and
 // can be modified and held indefinitely. The copy can be avoided by
-// using an argument of type *RawBytes instead; see the documentation
-// for RawBytes for restrictions on its use.
+// using an argument of type *[RawBytes] instead; see the documentation
+// for [RawBytes] for restrictions on its use.
 //
 // If an argument has type *interface{}, Scan copies the value
 // provided by the underlying driver without conversion. When scanning
@@ -3305,17 +3305,17 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 // the latter two, time.RFC3339Nano is used.
 //
 // Source values of type bool may be scanned into types *bool,
-// *interface{}, *string, *[]byte, or *RawBytes.
+// *interface{}, *string, *[]byte, or *[RawBytes].
 //
 // For scanning into *bool, the source may be true, false, 1, 0, or
-// string inputs parseable by strconv.ParseBool.
+// string inputs parseable by [strconv.ParseBool].
 //
 // Scan can also convert a cursor returned from a query, such as
 // "select cursor(select * from my_table) from dual", into a
-// *Rows value that can itself be scanned from. The parent
-// select query will close any cursor *Rows if the parent *Rows is closed.
+// *[Rows] value that can itself be scanned from. The parent
+// select query will close any cursor *[Rows] if the parent *[Rows] is closed.
 //
-// If any of the first arguments implementing Scanner returns an error,
+// If any of the first arguments implementing [Scanner] returns an error,
 // that error will be wrapped in the returned error.
 func (rs *Rows) Scan(dest ...any) error {
 	if rs.closemuScanHold {
@@ -3382,10 +3382,10 @@ func scanArgsContainRawBytes(args []any) bool {
 // hook through a test only mutex.
 var rowsCloseHook = func() func(*Rows, *error) { return nil }
 
-// Close closes the Rows, preventing further enumeration. If Next is called
+// Close closes the [Rows], preventing further enumeration. If [Rows.Next] is called
 // and returns false and there are no further result sets,
-// the Rows are closed automatically and it will suffice to check the
-// result of Err. Close is idempotent and does not affect the result of Err.
+// the [Rows] are closed automatically and it will suffice to check the
+// result of [Rows.Err]. Close is idempotent and does not affect the result of [Rows.Err].
 func (rs *Rows) Close() error {
 	// If the user's calling Close, they're done with their previous row's Scan
 	// results (any RawBytes memory), so we can release the read lock that would
@@ -3435,10 +3435,10 @@ type Row struct {
 }
 
 // Scan copies the columns from the matched row into the values
-// pointed at by dest. See the documentation on Rows.Scan for details.
+// pointed at by dest. See the documentation on [Rows.Scan] for details.
 // If more than one row matches the query,
 // Scan uses the first row and discards the rest. If no row matches
-// the query, Scan returns ErrNoRows.
+// the query, Scan returns [ErrNoRows].
 func (r *Row) Scan(dest ...any) error {
 	if r.err != nil {
 		return r.err
@@ -3479,9 +3479,9 @@ func (r *Row) Scan(dest ...any) error {
 }
 
 // Err provides a way for wrapping packages to check for
-// query errors without calling Scan.
+// query errors without calling [Row.Scan].
 // Err returns the error, if any, that was encountered while running the query.
-// If this error is not nil, this error will also be returned from Scan.
+// If this error is not nil, this error will also be returned from [Row.Scan].
 func (r *Row) Err() error {
 	return r.err
 }