From: cui fliter <imcusg@gmail.com>
Date: Fri, 13 Oct 2023 05:07:28 +0000 (+0800)
Subject: database: add available godoc link
X-Git-Tag: go1.22rc1~563
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=d1cb2483b70827f8f2f839fe7b0f140c910fc5b7;p=gostls13.git

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>
---

diff --git a/src/database/sql/driver/driver.go b/src/database/sql/driver/driver.go
index daf282bf74..5f6dccdbb9 100644
--- a/src/database/sql/driver/driver.go
+++ b/src/database/sql/driver/driver.go
@@ -8,26 +8,26 @@
 // Most code should use package sql.
 //
 // The driver interface has evolved over time. Drivers should implement
-// Connector and DriverContext interfaces.
-// The Connector.Connect and Driver.Open methods should never return ErrBadConn.
-// ErrBadConn should only be returned from Validator, SessionResetter, or
+// [Connector] and [DriverContext] interfaces.
+// The Connector.Connect and Driver.Open methods should never return [ErrBadConn].
+// [ErrBadConn] should only be returned from [Validator], [SessionResetter], or
 // a query method if the connection is already in an invalid (e.g. closed) state.
 //
-// All Conn implementations should implement the following interfaces:
-// Pinger, SessionResetter, and Validator.
+// All [Conn] implementations should implement the following interfaces:
+// [Pinger], [SessionResetter], and [Validator].
 //
-// If named parameters or context are supported, the driver's Conn should implement:
-// ExecerContext, QueryerContext, ConnPrepareContext, and ConnBeginTx.
+// If named parameters or context are supported, the driver's [Conn] should implement:
+// [ExecerContext], [QueryerContext], [ConnPrepareContext], and [ConnBeginTx].
 //
-// To support custom data types, implement NamedValueChecker. NamedValueChecker
+// To support custom data types, implement [NamedValueChecker]. [NamedValueChecker]
 // also allows queries to accept per-query options as a parameter by returning
-// ErrRemoveArgument from CheckNamedValue.
+// [ErrRemoveArgument] from CheckNamedValue.
 //
-// If multiple result sets are supported, Rows should implement RowsNextResultSet.
+// If multiple result sets are supported, [Rows] should implement [RowsNextResultSet].
 // If the driver knows how to describe the types present in the returned result
-// it should implement the following interfaces: RowsColumnTypeScanType,
-// RowsColumnTypeDatabaseTypeName, RowsColumnTypeLength, RowsColumnTypeNullable,
-// and RowsColumnTypePrecisionScale. A given row value may also return a Rows
+// it should implement the following interfaces: [RowsColumnTypeScanType],
+// [RowsColumnTypeDatabaseTypeName], [RowsColumnTypeLength], [RowsColumnTypeNullable],
+// and [RowsColumnTypePrecisionScale]. A given row value may also return a [Rows]
 // type, which may represent a database cursor value.
 //
 // Before a connection is returned to the connection pool after use, IsValid is
@@ -44,7 +44,7 @@ import (
 )
 
 // Value is a value that drivers must be able to handle.
-// It is either nil, a type handled by a database driver's NamedValueChecker
+// It is either nil, a type handled by a database driver's [NamedValueChecker]
 // interface, or an instance of one of these types:
 //
 //	int64
@@ -54,10 +54,10 @@ import (
 //	string
 //	time.Time
 //
-// If the driver supports cursors, a returned Value may also implement the Rows interface
+// If the driver supports cursors, a returned Value may also implement the [Rows] interface
 // in this package. This is used, for example, when a user selects a cursor
-// such as "select cursor(select * from my_table) from dual". If the Rows
-// from the select is closed, the cursor Rows will also be closed.
+// such as "select cursor(select * from my_table) from dual". If the [Rows]
+// from the select is closed, the cursor [Rows] will also be closed.
 type Value any
 
 // NamedValue holds both the value name and value.
@@ -78,7 +78,7 @@ type NamedValue struct {
 // Driver is the interface that must be implemented by a database
 // driver.
 //
-// Database drivers may implement DriverContext for access
+// Database drivers may implement [DriverContext] for access
 // to contexts and to parse the name only once for a pool of connections,
 // instead of once per connection.
 type Driver interface {
@@ -94,10 +94,10 @@ type Driver interface {
 	Open(name string) (Conn, error)
 }
 
-// If a Driver implements DriverContext, then sql.DB will call
-// OpenConnector to obtain a Connector and then invoke
-// that Connector's Connect method to obtain each needed connection,
-// instead of invoking the Driver's Open method for each connection.
+// If a [Driver] implements [DriverContext], then sql.DB will call
+// OpenConnector to obtain a [Connector] and then invoke
+// that [Connector]'s Connect method to obtain each needed connection,
+// instead of invoking the [Driver]'s Open method for each connection.
 // The two-step sequence allows drivers to parse the name just once
 // and also provides access to per-Conn contexts.
 type DriverContext interface {
@@ -110,13 +110,13 @@ type DriverContext interface {
 // and can create any number of equivalent Conns for use
 // by multiple goroutines.
 //
-// A Connector can be passed to sql.OpenDB, to allow drivers
+// A Connector can be passed to [database/sql.OpenDB], to allow drivers
 // to implement their own sql.DB constructors, or returned by
-// DriverContext's OpenConnector method, to allow drivers
+// [DriverContext]'s OpenConnector method, to allow drivers
 // access to context and to avoid repeated parsing of driver
 // configuration.
 //
-// If a Connector implements io.Closer, the sql package's DB.Close
+// If a Connector implements [io.Closer], the [database/sql.DB.Close]
 // method will call Close and return error (if any).
 type Connector interface {
 	// Connect returns a connection to the database.
@@ -148,7 +148,7 @@ type Connector interface {
 var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
 
 // ErrBadConn should be returned by a driver to signal to the sql
-// package that a driver.Conn is in a bad state (such as the server
+// package that a [driver.Conn] is in a bad state (such as the server
 // having earlier closed the connection) and the sql package should
 // retry on a new connection.
 //
@@ -161,65 +161,65 @@ var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
 // wrap ErrBadConn or implement the Is(error) bool method.
 var ErrBadConn = errors.New("driver: bad connection")
 
-// Pinger is an optional interface that may be implemented by a Conn.
+// Pinger is an optional interface that may be implemented by a [Conn].
 //
-// If a Conn does not implement Pinger, the sql package's DB.Ping and
-// DB.PingContext will check if there is at least one Conn available.
+// If a [Conn] does not implement Pinger, the [database/sql.DB.Ping] and
+// [database/sql.DB.PingContext] will check if there is at least one [Conn] available.
 //
-// If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove
-// the Conn from pool.
+// If Conn.Ping returns [ErrBadConn], [database/sql.DB.Ping] and [database/sql.DB.PingContext] will remove
+// the [Conn] from pool.
 type Pinger interface {
 	Ping(ctx context.Context) error
 }
 
 // Execer is an optional interface that may be implemented by a Conn.
 //
-// If a Conn implements neither ExecerContext nor Execer,
-// the sql package's DB.Exec will first prepare a query, execute the statement,
+// If a [Conn] implements neither [ExecerContext] nor Execer,
+// the [database/sql.DB.Exec] will first prepare a query, execute the statement,
 // and then close the statement.
 //
-// Exec may return ErrSkip.
+// Exec may return [ErrSkip].
 //
-// Deprecated: Drivers should implement ExecerContext instead.
+// Deprecated: Drivers should implement [ExecerContext] instead.
 type Execer interface {
 	Exec(query string, args []Value) (Result, error)
 }
 
-// ExecerContext is an optional interface that may be implemented by a Conn.
+// ExecerContext is an optional interface that may be implemented by a [Conn].
 //
-// If a Conn does not implement ExecerContext, the sql package's DB.Exec
-// will fall back to Execer; if the Conn does not implement Execer either,
-// DB.Exec will first prepare a query, execute the statement, and then
+// If a Conn does not implement ExecerContext, the [database/sql.DB.Exec]
+// will fall back to [Execer]; if the Conn does not implement Execer either,
+// [database/sql.DB.Exec] will first prepare a query, execute the statement, and then
 // close the statement.
 //
-// ExecContext may return ErrSkip.
+// ExecContext may return [ErrSkip].
 //
 // ExecContext must honor the context timeout and return when the context is canceled.
 type ExecerContext interface {
 	ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
 }
 
-// Queryer is an optional interface that may be implemented by a Conn.
+// Queryer is an optional interface that may be implemented by a [Conn].
 //
-// If a Conn implements neither QueryerContext nor Queryer,
-// the sql package's DB.Query will first prepare a query, execute the statement,
+// If a Conn implements neither [QueryerContext] nor Queryer,
+// the [database/sql.DB.Query] will first prepare a query, execute the statement,
 // and then close the statement.
 //
-// Query may return ErrSkip.
+// Query may return [ErrSkip].
 //
-// Deprecated: Drivers should implement QueryerContext instead.
+// Deprecated: Drivers should implement [QueryerContext] instead.
 type Queryer interface {
 	Query(query string, args []Value) (Rows, error)
 }
 
 // QueryerContext is an optional interface that may be implemented by a Conn.
 //
-// If a Conn does not implement QueryerContext, the sql package's DB.Query
-// will fall back to Queryer; if the Conn does not implement Queryer either,
-// DB.Query will first prepare a query, execute the statement, and then
+// If a [Conn] does not implement QueryerContext, the [database/sql.DB.Query]
+// will fall back to [Queryer]; if the [Conn] does not implement [Queryer] either,
+// [database/sql.DB.Query] will first prepare a query, execute the statement, and then
 // close the statement.
 //
-// QueryContext may return ErrSkip.
+// QueryContext may return [ErrSkip].
 //
 // QueryContext must honor the context timeout and return when the context is canceled.
 type QueryerContext interface {
@@ -253,7 +253,7 @@ type Conn interface {
 	Begin() (Tx, error)
 }
 
-// ConnPrepareContext enhances the Conn interface with context.
+// ConnPrepareContext enhances the [Conn] interface with context.
 type ConnPrepareContext interface {
 	// PrepareContext returns a prepared statement, bound to this connection.
 	// context is for the preparation of the statement,
@@ -261,7 +261,7 @@ type ConnPrepareContext interface {
 	PrepareContext(ctx context.Context, query string) (Stmt, error)
 }
 
-// IsolationLevel is the transaction isolation level stored in TxOptions.
+// IsolationLevel is the transaction isolation level stored in [TxOptions].
 //
 // This type should be considered identical to sql.IsolationLevel along
 // with any values defined on it.
@@ -269,13 +269,13 @@ type IsolationLevel int
 
 // TxOptions holds the transaction options.
 //
-// This type should be considered identical to sql.TxOptions.
+// This type should be considered identical to [database/sql.TxOptions].
 type TxOptions struct {
 	Isolation IsolationLevel
 	ReadOnly  bool
 }
 
-// ConnBeginTx enhances the Conn interface with context and TxOptions.
+// ConnBeginTx enhances the [Conn] interface with context and [TxOptions].
 type ConnBeginTx interface {
 	// BeginTx starts and returns a new transaction.
 	// If the context is canceled by the user the sql package will
@@ -292,7 +292,7 @@ type ConnBeginTx interface {
 	BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
 }
 
-// SessionResetter may be implemented by Conn to allow drivers to reset the
+// SessionResetter may be implemented by [Conn] to allow drivers to reset the
 // session state associated with the connection and to signal a bad connection.
 type SessionResetter interface {
 	// ResetSession is called prior to executing a query on the connection
@@ -301,7 +301,7 @@ type SessionResetter interface {
 	ResetSession(ctx context.Context) error
 }
 
-// Validator may be implemented by Conn to allow drivers to
+// Validator may be implemented by [Conn] to allow drivers to
 // signal if a connection is valid or if it should be discarded.
 //
 // If implemented, drivers may return the underlying error from queries,
@@ -324,7 +324,7 @@ type Result interface {
 	RowsAffected() (int64, error)
 }
 
-// Stmt is a prepared statement. It is bound to a Conn and not
+// Stmt is a prepared statement. It is bound to a [Conn] and not
 // used by multiple goroutines concurrently.
 type Stmt interface {
 	// Close closes the statement.
@@ -360,7 +360,7 @@ type Stmt interface {
 	Query(args []Value) (Rows, error)
 }
 
-// StmtExecContext enhances the Stmt interface by providing Exec with context.
+// StmtExecContext enhances the [Stmt] interface by providing Exec with context.
 type StmtExecContext interface {
 	// ExecContext executes a query that doesn't return rows, such
 	// as an INSERT or UPDATE.
@@ -369,7 +369,7 @@ type StmtExecContext interface {
 	ExecContext(ctx context.Context, args []NamedValue) (Result, error)
 }
 
-// StmtQueryContext enhances the Stmt interface by providing Query with context.
+// StmtQueryContext enhances the [Stmt] interface by providing Query with context.
 type StmtQueryContext interface {
 	// QueryContext executes a query that may return rows, such as a
 	// SELECT.
@@ -378,26 +378,26 @@ type StmtQueryContext interface {
 	QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
 }
 
-// ErrRemoveArgument may be returned from NamedValueChecker to instruct the
+// ErrRemoveArgument may be returned from [NamedValueChecker] to instruct the
 // sql package to not pass the argument to the driver query interface.
 // Return when accepting query specific options or structures that aren't
 // SQL query arguments.
 var ErrRemoveArgument = errors.New("driver: remove argument from query")
 
-// NamedValueChecker may be optionally implemented by Conn or Stmt. It provides
+// NamedValueChecker may be optionally implemented by [Conn] or [Stmt]. It provides
 // the driver more control to handle Go and database types beyond the default
 // Values types allowed.
 //
 // The sql package checks for value checkers in the following order,
-// stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker,
-// Stmt.ColumnConverter, DefaultParameterConverter.
+// stopping at the first found match: [database/sql.Stmt.NamedValueChecker],
+// Conn.NamedValueChecker, [database/sql.Stmt.ColumnConverter], [DefaultParameterConverter].
 //
-// If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in
+// If CheckNamedValue returns [ErrRemoveArgument], the [NamedValue] will not be included in
 // the final query arguments. This may be used to pass special options to
 // the query itself.
 //
-// If ErrSkip is returned the column converter error checking
-// path is used for the argument. Drivers may wish to return ErrSkip after
+// If [ErrSkip] is returned the column converter error checking
+// path is used for the argument. Drivers may wish to return [ErrSkip] after
 // they have exhausted their own special cases.
 type NamedValueChecker interface {
 	// CheckNamedValue is called before passing arguments to the driver
@@ -406,11 +406,11 @@ type NamedValueChecker interface {
 	CheckNamedValue(*NamedValue) error
 }
 
-// ColumnConverter may be optionally implemented by Stmt if the
+// ColumnConverter may be optionally implemented by [Stmt] if the
 // statement is aware of its own columns' types and can convert from
-// any type to a driver Value.
+// any type to a driver [Value].
 //
-// Deprecated: Drivers should implement NamedValueChecker.
+// Deprecated: Drivers should implement [NamedValueChecker].
 type ColumnConverter interface {
 	// ColumnConverter returns a ValueConverter for the provided
 	// column index. If the type of a specific column isn't known
@@ -442,7 +442,7 @@ type Rows interface {
 	Next(dest []Value) error
 }
 
-// RowsNextResultSet extends the Rows interface by providing a way to signal
+// RowsNextResultSet extends the [Rows] interface by providing a way to signal
 // the driver to advance to the next result set.
 type RowsNextResultSet interface {
 	Rows
@@ -458,15 +458,15 @@ type RowsNextResultSet interface {
 	NextResultSet() error
 }
 
-// RowsColumnTypeScanType may be implemented by Rows. It should return
+// RowsColumnTypeScanType may be implemented by [Rows]. It should return
 // the value type that can be used to scan types into. For example, the database
-// column type "bigint" this should return "reflect.TypeOf(int64(0))".
+// column type "bigint" this should return "[reflect.TypeOf](int64(0))".
 type RowsColumnTypeScanType interface {
 	Rows
 	ColumnTypeScanType(index int) reflect.Type
 }
 
-// RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the
+// RowsColumnTypeDatabaseTypeName may be implemented by [Rows]. It should return the
 // database system type name without the length. Type names should be uppercase.
 // Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT",
 // "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML",
@@ -476,7 +476,7 @@ type RowsColumnTypeDatabaseTypeName interface {
 	ColumnTypeDatabaseTypeName(index int) string
 }
 
-// RowsColumnTypeLength may be implemented by Rows. It should return the length
+// RowsColumnTypeLength may be implemented by [Rows]. It should return the length
 // of the column type if the column is a variable length type. If the column is
 // not a variable length type ok should return false.
 // If length is not limited other than system limits, it should return math.MaxInt64.
@@ -493,7 +493,7 @@ type RowsColumnTypeLength interface {
 	ColumnTypeLength(index int) (length int64, ok bool)
 }
 
-// RowsColumnTypeNullable may be implemented by Rows. The nullable value should
+// RowsColumnTypeNullable may be implemented by [Rows]. The nullable value should
 // be true if it is known the column may be null, or false if the column is known
 // to be not nullable.
 // If the column nullability is unknown, ok should be false.
@@ -502,7 +502,7 @@ type RowsColumnTypeNullable interface {
 	ColumnTypeNullable(index int) (nullable, ok bool)
 }
 
-// RowsColumnTypePrecisionScale may be implemented by Rows. It should return
+// RowsColumnTypePrecisionScale may be implemented by [Rows]. It should return
 // the precision and scale for decimal types. If not applicable, ok should be false.
 // The following are examples of returned values for various types:
 //
@@ -520,7 +520,7 @@ type Tx interface {
 	Rollback() error
 }
 
-// RowsAffected implements Result for an INSERT or UPDATE operation
+// RowsAffected implements [Result] for an INSERT or UPDATE operation
 // which mutates a number of rows.
 type RowsAffected int64
 
@@ -534,9 +534,9 @@ func (v RowsAffected) RowsAffected() (int64, error) {
 	return int64(v), nil
 }
 
-// ResultNoRows is a pre-defined Result for drivers to return when a DDL
+// ResultNoRows is a pre-defined [Result] for drivers to return when a DDL
 // command (such as a CREATE TABLE) succeeds. It returns an error for both
-// LastInsertId and RowsAffected.
+// LastInsertId and [RowsAffected].
 var ResultNoRows noRows
 
 type noRows struct{}
diff --git a/src/database/sql/driver/types.go b/src/database/sql/driver/types.go
index c4a253b3e5..4fec453cdd 100644
--- a/src/database/sql/driver/types.go
+++ b/src/database/sql/driver/types.go
@@ -17,15 +17,15 @@ import (
 // driver package to provide consistent implementations of conversions
 // between drivers. The ValueConverters have several uses:
 //
-//   - converting from the Value types as provided by the sql package
+//   - converting from the [Value] types as provided by the sql package
 //     into a database table's specific column type and making sure it
 //     fits, such as making sure a particular int64 fits in a
 //     table's uint16 column.
 //
 //   - converting a value as given from the database into one of the
-//     driver Value types.
+//     driver [Value] types.
 //
-//   - by the sql package, for converting from a driver's Value type
+//   - by the sql package, for converting from a driver's [Value] type
 //     to a user's type in a scan.
 type ValueConverter interface {
 	// ConvertValue converts a value to a driver Value.
@@ -42,7 +42,7 @@ type Valuer interface {
 	Value() (Value, error)
 }
 
-// Bool is a ValueConverter that converts input values to bools.
+// Bool is a [ValueConverter] that converts input values to bool.
 //
 // The conversion rules are:
 //   - booleans are returned unchanged
@@ -50,7 +50,7 @@ type Valuer interface {
 //     1 is true
 //     0 is false,
 //     other integers are an error
-//   - for strings and []byte, same rules as strconv.ParseBool
+//   - for strings and []byte, same rules as [strconv.ParseBool]
 //   - all other types are an error
 var Bool boolType
 
@@ -97,7 +97,7 @@ func (boolType) ConvertValue(src any) (Value, error) {
 	return nil, fmt.Errorf("sql/driver: couldn't convert %v (%T) into type bool", src, src)
 }
 
-// Int32 is a ValueConverter that converts input values to int64,
+// Int32 is a [ValueConverter] that converts input values to int64,
 // respecting the limits of an int32 value.
 var Int32 int32Type
 
@@ -130,7 +130,7 @@ func (int32Type) ConvertValue(v any) (Value, error) {
 	return nil, fmt.Errorf("sql/driver: unsupported value %v (type %T) converting to int32", v, v)
 }
 
-// String is a ValueConverter that converts its input to a string.
+// String is a [ValueConverter] that converts its input to a string.
 // If the value is already a string or []byte, it's unchanged.
 // If the value is of another type, conversion to string is done
 // with fmt.Sprintf("%v", v).
@@ -146,8 +146,8 @@ func (stringType) ConvertValue(v any) (Value, error) {
 	return fmt.Sprintf("%v", v), nil
 }
 
-// Null is a type that implements ValueConverter by allowing nil
-// values but otherwise delegating to another ValueConverter.
+// Null is a type that implements [ValueConverter] by allowing nil
+// values but otherwise delegating to another [ValueConverter].
 type Null struct {
 	Converter ValueConverter
 }
@@ -159,8 +159,8 @@ func (n Null) ConvertValue(v any) (Value, error) {
 	return n.Converter.ConvertValue(v)
 }
 
-// NotNull is a type that implements ValueConverter by disallowing nil
-// values but otherwise delegating to another ValueConverter.
+// NotNull is a type that implements [ValueConverter] by disallowing nil
+// values but otherwise delegating to another [ValueConverter].
 type NotNull struct {
 	Converter ValueConverter
 }
@@ -172,7 +172,7 @@ func (n NotNull) ConvertValue(v any) (Value, error) {
 	return n.Converter.ConvertValue(v)
 }
 
-// IsValue reports whether v is a valid Value parameter type.
+// IsValue reports whether v is a valid [Value] parameter type.
 func IsValue(v any) bool {
 	if v == nil {
 		return true
@@ -193,18 +193,19 @@ func IsScanValue(v any) bool {
 }
 
 // DefaultParameterConverter is the default implementation of
-// ValueConverter that's used when a Stmt doesn't implement
-// ColumnConverter.
+// [ValueConverter] that's used when a [Stmt] doesn't implement
+// [ColumnConverter].
 //
 // DefaultParameterConverter returns its argument directly if
-// IsValue(arg). Otherwise, if the argument implements Valuer, its
-// Value method is used to return a Value. As a fallback, the provided
-// argument's underlying type is used to convert it to a Value:
+// IsValue(arg). Otherwise, if the argument implements [Valuer], its
+// Value method is used to return a [Value]. As a fallback, the provided
+// argument's underlying type is used to convert it to a [Value]:
 // underlying integer types are converted to int64, floats to float64,
 // bool, string, and []byte to themselves. If the argument is a nil
-// pointer, ConvertValue returns a nil Value. If the argument is a
-// non-nil pointer, it is dereferenced and ConvertValue is called
-// recursively. Other types are an error.
+// pointer, [defaultConverter.ConvertValue] returns a nil [Value].
+// If the argument is a non-nil pointer, it is dereferenced and
+// [defaultConverter.ConvertValue] is called recursively. Other types
+// are an error.
 var DefaultParameterConverter defaultConverter
 
 type defaultConverter struct{}
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
 }