database/sql: add godoc links

Add godoc links in database/sql and database/sql/driver.

Change-Id: I96ed79645a7cc656f5d23450ba3cfe005b04b31a
Reviewed-on: https://go-review.googlesource.com/c/go/+/486815
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Benny Siegert <bsiegert@gmail.com>

src/database/sql/driver/driver.go

@@ -5,7 +5,7 @@
 // Package driver defines interfaces to be implemented by database
 // drivers as used by package sql.
 //
-// Most code should use package sql.
+// Most code should use the [database/sql] package.
 //
 // The driver interface has evolved over time. Drivers should implement
 // [Connector] and [DriverContext] interfaces.
@@ -30,11 +30,12 @@
 // 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
+// If a [Conn] implements [Validator], then the IsValid method is called
-// called if implemented. Before a connection is reused for another query,
+// before returning the connection to the connection pool. If an entry in the
-// ResetSession is called if implemented. If a connection is never returned to the
+// connection pool implements [SessionResetter], then ResetSession
-// connection pool but immediately reused, then ResetSession is called prior to
+// is called before reusing the connection for another query. If a connection is
-// reuse but IsValid is not called.
+// never returned to the connection pool but is immediately reused, then
+// ResetSession is called prior to reuse but IsValid is not called.
 package driver
 
 import (
@@ -94,12 +95,12 @@ type Driver interface {
 	Open(name string) (Conn, error)
 }
 
-// If a [Driver] implements [DriverContext], then sql.DB will call
+// If a [Driver] implements DriverContext, then [database/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.
+// and also provides access to per-[Conn] contexts.
 type DriverContext interface {
 	// OpenConnector must parse the name in the same format that Driver.Open
 	// parses the name parameter.
@@ -111,13 +112,13 @@ type DriverContext interface {
 // by multiple goroutines.
 //
 // A Connector can be passed to [database/sql.OpenDB], to allow drivers
-// to implement their own sql.DB constructors, or returned by
+// to implement their own [database/sql.DB] constructors, or returned by
 // [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 [database/sql.DB.Close]
-// method will call Close and return error (if any).
+// method will call the Close method and return error (if any).
 type Connector interface {
 	// Connect returns a connection to the database.
 	// Connect may return a cached connection (one previously
@@ -147,9 +148,9 @@ type Connector interface {
 // documented.
 var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
 
-// ErrBadConn should be returned by a driver to signal to the sql
+// ErrBadConn should be returned by a driver to signal to the [database/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
+// having earlier closed the connection) and the [database/sql] package should
 // retry on a new connection.
 //
 // To prevent duplicate operations, ErrBadConn should NOT be returned
@@ -157,7 +158,7 @@ var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
 // performed the operation. Even if the server sends back an error,
 // you shouldn't return ErrBadConn.
 //
-// Errors will be checked using errors.Is. An error may
+// Errors will be checked using [errors.Is]. An error may
 // wrap ErrBadConn or implement the Is(error) bool method.
 var ErrBadConn = errors.New("driver: bad connection")
 
@@ -172,9 +173,9 @@ type Pinger interface {
 	Ping(ctx context.Context) error
 }
 
-// Execer is an optional interface that may be implemented by a Conn.
+// Execer is an optional interface that may be implemented by a [Conn].
 //
-// If a [Conn] implements neither [ExecerContext] nor Execer,
+// 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.
 //
@@ -187,7 +188,7 @@ type Execer interface {
 
 // ExecerContext is an optional interface that may be implemented by a [Conn].
 //
-// If a Conn does not implement ExecerContext, the [database/sql.DB.Exec]
+// 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.
@@ -201,7 +202,7 @@ type ExecerContext interface {
 
 // Queryer is an optional interface that may be implemented by a [Conn].
 //
-// If a Conn implements neither [QueryerContext] nor Queryer,
+// 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.
 //
@@ -212,7 +213,7 @@ type Queryer interface {
 	Query(query string, args []Value) (Rows, error)
 }
 
-// QueryerContext is an optional interface that may be implemented by a Conn.
+// QueryerContext is an optional interface that may be implemented by a [Conn].
 //
 // 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,
@@ -263,7 +264,7 @@ type ConnPrepareContext interface {
 
 // IsolationLevel is the transaction isolation level stored in [TxOptions].
 //
-// This type should be considered identical to sql.IsolationLevel along
+// This type should be considered identical to [database/sql.IsolationLevel] along
 // with any values defined on it.
 type IsolationLevel int
 
@@ -379,18 +380,18 @@ type StmtQueryContext interface {
 }
 
 // ErrRemoveArgument may be returned from [NamedValueChecker] to instruct the
-// sql package to not pass the argument to the driver query interface.
+// [database/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
 // the driver more control to handle Go and database types beyond the default
-// Values types allowed.
+// [Value] types allowed.
 //
-// The sql package checks for value checkers in the following order,
+// The [database/sql] package checks for value checkers in the following order,
-// stopping at the first found match: [database/sql.Stmt.NamedValueChecker],
+// stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker,
-// Conn.NamedValueChecker, [database/sql.Stmt.ColumnConverter], [DefaultParameterConverter].
+// Stmt.ColumnConverter, [DefaultParameterConverter].
 //
 // If CheckNamedValue returns [ErrRemoveArgument], the [NamedValue] will not be included in
 // the final query arguments. This may be used to pass special options to
@@ -479,7 +480,7 @@ type RowsColumnTypeDatabaseTypeName interface {
 // 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.
+// If length is not limited other than system limits, it should return [math.MaxInt64].
 // The following are examples of returned values for various types:
 //
 //	TEXT          (math.MaxInt64, true)

src/database/sql/driver/types.go

@@ -25,7 +25,7 @@ import (
 //   - converting a value as given from the database into one of the
 //     driver [Value] types.
 //
-//   - by the sql package, for converting from a driver's [Value] type
+//   - by the [database/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.
@@ -35,7 +35,7 @@ type ValueConverter interface {
 // Valuer is the interface providing the Value method.
 //
 // Types implementing Valuer interface are able to convert
-// themselves to a driver Value.
+// themselves to a driver [Value].
 type Valuer interface {
 	// Value returns a driver Value.
 	// Value must not panic.
@@ -186,7 +186,7 @@ func IsValue(v any) bool {
 	return false
 }
 
-// IsScanValue is equivalent to IsValue.
+// IsScanValue is equivalent to [IsValue].
 // It exists for compatibility.
 func IsScanValue(v any) bool {
 	return IsValue(v)
@@ -202,9 +202,9 @@ func IsScanValue(v any) bool {
 // 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, [defaultConverter.ConvertValue] returns a nil [Value].
+// 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
+// defaultConverter.ConvertValue is called recursively. Other types
 // are an error.
 var DefaultParameterConverter defaultConverter
 

src/database/sql/sql.go

@@ -73,7 +73,7 @@ func Drivers() []string {
 }
 
 // A NamedArg is a named argument. NamedArg values may be used as
-// arguments to Query or Exec and bind to the corresponding named
+// arguments to [DB.Query] or [DB.Exec] and bind to the corresponding named
 // parameter in the SQL statement.
 //
 // For a more concise way to create NamedArg values, see
@@ -118,7 +118,7 @@ func Named(name string, value any) NamedArg {
 // IsolationLevel is the transaction isolation level used in [TxOptions].
 type IsolationLevel int
 
-// Various isolation levels that drivers may support in BeginTx.
+// Various isolation levels that drivers may support in [DB.BeginTx].
 // If a driver does not support a given isolation level an error may be returned.
 //
 // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.
@@ -168,8 +168,8 @@ type TxOptions struct {
 }
 
 // RawBytes is a byte slice that holds a reference to memory owned by
-// the database itself. After a Scan into a RawBytes, the slice is only
+// the database itself. After a [Rows.Scan] into a RawBytes, the slice is only
-// valid until the next call to Next, Scan, or Close.
+// valid until the next call to [Rows.Next], [Rows.Scan], or [Rows.Close].
 type RawBytes []byte
 
 // NullString represents a string that may be null.
@@ -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 [Rows.Scan].
 type Scanner interface {
 	// Scan assigns a value from a database driver.
 	//
@@ -468,8 +468,8 @@ type Out struct {
 	In bool
 }
 
-// ErrNoRows is returned by Scan when QueryRow doesn't return a
+// ErrNoRows is returned by [Row.Scan] when [DB.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")
 
@@ -481,10 +481,10 @@ var ErrNoRows = errors.New("sql: no rows in result set")
 // 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
+// returned [Tx] is bound to a single connection. Once [Tx.Commit] or
-// Rollback is called on the transaction, that transaction's
+// [Tx.Rollback] is called on the transaction, that transaction's
 // connection is returned to [DB]'s idle connection pool. The pool size
-// can be controlled with SetMaxIdleConns.
+// can be controlled with [DB.SetMaxIdleConns].
 type DB struct {
 	// Total time waited for new connections.
 	waitDuration atomic.Int64
@@ -777,7 +777,7 @@ func (db *DB) removeDepLocked(x finalCloser, dep any) func() error {
 
 // This is the size of the connectionOpener request chan (DB.openerCh).
 // This value should be larger than the maximum typical value
-// used for db.maxOpen. If maxOpen is significantly larger than
+// used for DB.maxOpen. If maxOpen is significantly larger than
 // connectionRequestQueueSize then it is possible for ALL calls into the *DB
 // to block until the connectionOpener can satisfy the backlog of requests.
 var connectionRequestQueueSize = 1000000
@@ -795,17 +795,17 @@ func (t dsnConnector) Driver() driver.Driver {
 	return t.driver
 }
 
-// OpenDB opens a database using a Connector, allowing drivers to
+// OpenDB opens a database using a [driver.Connector], allowing drivers to
 // 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.
 //
 // OpenDB may just validate its arguments without creating a connection
 // to the database. To verify that the data source name is valid, call
-// Ping.
+// [DB.Ping].
 //
 // The returned [DB] is safe for concurrent use by multiple goroutines
 // and maintains its own pool of idle connections. Thus, the OpenDB
@@ -831,13 +831,13 @@ 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.
 //
 // Open may just validate its arguments without creating a connection
 // to the database. To verify that the data source name is valid, call
-// Ping.
+// [DB.Ping].
 //
 // The returned [DB] is safe for concurrent use by multiple goroutines
 // and maintains its own pool of idle connections. Thus, the Open
@@ -895,7 +895,7 @@ func (db *DB) PingContext(ctx context.Context) error {
 // establishing a connection if necessary.
 //
 // Ping uses [context.Background] internally; to specify the context, use
-// [PingContext].
+// [DB.PingContext].
 func (db *DB) Ping() error {
 	return db.PingContext(context.Background())
 }
@@ -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 [DB.Close] method
+// The caller must call the statement's [*Stmt.Close] method
 // when the statement is no longer needed.
 //
 // The provided context is used for the preparation of the statement, not for the
@@ -1596,7 +1596,7 @@ func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
 // Prepare creates a prepared statement for later queries or executions.
 // Multiple queries or executions may be run concurrently from the
 // returned statement.
-// The caller must call the statement's Close method
+// The caller must call the statement's [*Stmt.Close] method
 // when the statement is no longer needed.
 //
 // Prepare uses [context.Background] internally; to specify the context, use
@@ -1825,8 +1825,8 @@ 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, [*Row.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...)
@@ -1836,8 +1836,8 @@ 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, [*Row.Scan] scans the first selected row and discards
 // the rest.
 //
 // QueryRow uses [context.Background] internally; to specify the context, use
@@ -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.
+// the [*Row.Scan] method is called.
-// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, the [*Row.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 [Conn.Close] method
+// The caller must call the statement's [*Stmt.Close] method
 // when the statement is no longer needed.
 //
 // The provided context is used for the preparation of the statement, not for the
@@ -2057,7 +2057,7 @@ 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
+// 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
@@ -2257,7 +2257,7 @@ func (tx *Tx) txCtx() context.Context {
 }
 
 // closemuRUnlockRelease is used as a func(error) method value in
-// ExecContext and QueryContext. Unlocking in the releaseConn keeps
+// [DB.ExecContext] and [DB.QueryContext]. Unlocking in the releaseConn keeps
 // the driver conn from being returned to the connection pool until
 // the Rows has been closed.
 func (tx *Tx) closemuRUnlockRelease(error) {
@@ -2536,8 +2536,8 @@ func (tx *Tx) Query(query string, args ...any) (*Rows, error) {
 // 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, the [*Row.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...)
@@ -2547,8 +2547,8 @@ 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, the [*Row.Scan] scans the first selected row and discards
 // the rest.
 //
 // QueryRow uses [context.Background] internally; to specify the context, use
@@ -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()
@@ -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.
+// 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, the [*Row.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.
+// 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].
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// Otherwise, the [*Row.Scan] scans the first selected row and discards
 // the rest.
 //
 // Example usage:
@@ -3271,9 +3271,9 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 //	*bool
 //	*float32, *float64
 //	*interface{}
-//	*[RawBytes]
+//	*RawBytes
-//	*[Rows] (cursor value)
+//	*Rows (cursor value)
-//	any type implementing [Scanner] (see Scanner docs)
+//	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,7 +3292,7 @@ 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
+// 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
@@ -3300,20 +3300,20 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
 // from a source value of type []byte to *interface{}, a copy of the
 // slice is made and the caller owns the result.
 //
-// Source values of type time.Time may be scanned into values of type
+// Source values of type [time.Time] may be scanned into values of type
 // *time.Time, *interface{}, *string, or *[]byte. When converting to
-// the latter two, time.RFC3339Nano is used.
+// 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].
 //
 // 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
+// [*Rows] value that can itself be scanned from. The parent
-// select query will close any cursor *[Rows] if the parent *[Rows] is closed.
+// select query will close any cursor [*Rows] if the parent [*Rows] is closed.
 //
 // If any of the first arguments implementing [Scanner] returns an error,
 // that error will be wrapped in the returned error.
@@ -3427,7 +3427,7 @@ func (rs *Rows) close(err error) error {
 	return err
 }
 
-// Row is the result of calling QueryRow to select a single row.
+// Row is the result of calling [DB.QueryRow] to select a single row.
 type Row struct {
 	// One of these two will be non-nil:
 	err  error // deferred error for easy chaining