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>

1 files changed, 50 insertions, 50 deletions

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index e70aa8b550..44b202192a 100644
--- a/src/database/sql/sql.go
+++ b/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
-// valid until the next call to Next, Scan, or Close.
+// the database itself. After a [Rows.Scan] into a RawBytes, the slice is only
+// 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
-// row. In such a case, QueryRow returns a placeholder *[Row] value that
+// 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
 // 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
-// Rollback is called on the transaction, that transaction's
+// returned [Tx] is bound to a single connection. Once [Tx.Commit] or
+// [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].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
+// 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].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
+// 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.
-// 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 [*Row.Scan] method is called.
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
+// 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].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
+// 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].
-// Otherwise, the *[Row]'s Scan scans the first selected row and discards
+// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows].
+// 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.
-// 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.Scan] will return [ErrNoRows].
+// 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.
-// 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.Scan] will return [ErrNoRows].
+// 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]
-//	*[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,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
-// 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,
 // 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