Merge pull request #2531 from dolmen-go/godoc-add-links

doc: add godoc links

Author: jackc

batch.go

@@ -8,7 +8,7 @@ import (
 	"github.com/jackc/pgx/v5/pgconn"
 )
 
-// QueuedQuery is a query that has been queued for execution via a Batch.
+// QueuedQuery is a query that has been queued for execution via a [Batch].
 type QueuedQuery struct {
 	SQL       string
 	Arguments []any
@@ -46,7 +46,7 @@ func (qq *QueuedQuery) QueryRow(fn func(row Row) error) {
 //
 // Note: for simple batch insert uses where it is not required to handle
 // each potential error individually, it's sufficient to not set any callbacks,
-// and just handle the return value of BatchResults.Close.
+// and just handle the return value of [BatchResults.Close].
 func (qq *QueuedQuery) Exec(fn func(ct pgconn.CommandTag) error) {
 	qq.Fn = func(br BatchResults) error {
 		ct, err := br.Exec()
@@ -65,12 +65,13 @@ type Batch struct {
 }
 
 // Queue queues a query to batch b. query can be an SQL query or the name of a prepared statement. The only pgx option
-// argument that is supported is QueryRewriter. Queries are executed using the connection's DefaultQueryExecMode.
+// argument that is supported is [QueryRewriter]. Queries are executed using the connection's DefaultQueryExecMode
+// (see [ConnConfig.DefaultQueryExecMode]).
 //
-// While query can contain multiple statements if the connection's DefaultQueryExecMode is QueryModeSimple, this should
-// be avoided. QueuedQuery.Fn must not be set as it will only be called for the first query. That is, QueuedQuery.Query,
-// QueuedQuery.QueryRow, and QueuedQuery.Exec must not be called. In addition, any error messages or tracing that
-// include the current query may reference the wrong query.
+// While query can contain multiple statements if the connection's DefaultQueryExecMode is [QueryExecModeSimpleProtocol],
+// this should be avoided. QueuedQuery.Fn must not be set as it will only be called for the first query. That is,
+// [QueuedQuery.Query], [QueuedQuery.QueryRow], and [QueuedQuery.Exec] must not be called. In addition, any error
+// messages or tracing that include the current query may reference the wrong query.
 func (b *Batch) Queue(query string, arguments ...any) *QueuedQuery {
 	qq := &QueuedQuery{
 		SQL:       query,
@@ -86,20 +87,20 @@ func (b *Batch) Len() int {
 }
 
 type BatchResults interface {
-	// Exec reads the results from the next query in the batch as if the query has been sent with Conn.Exec. Prefer
+	// Exec reads the results from the next query in the batch as if the query has been sent with [Conn.Exec]. Prefer
 	// calling Exec on the QueuedQuery, or just calling Close.
 	Exec() (pgconn.CommandTag, error)
 
-	// Query reads the results from the next query in the batch as if the query has been sent with Conn.Query. Prefer
-	// calling Query on the QueuedQuery.
+	// Query reads the results from the next query in the batch as if the query has been sent with [Conn.Query]. Prefer
+	// calling [QueuedQuery.Query].
 	Query() (Rows, error)
 
-	// QueryRow reads the results from the next query in the batch as if the query has been sent with Conn.QueryRow.
-	// Prefer calling QueryRow on the QueuedQuery.
+	// QueryRow reads the results from the next query in the batch as if the query has been sent with [Conn.QueryRow].
+	// Prefer calling [QueuedQuery.QueryRow].
 	QueryRow() Row
 
 	// Close closes the batch operation. All unread results are read and any callback functions registered with
-	// QueuedQuery.Query, QueuedQuery.QueryRow, or QueuedQuery.Exec will be called. If a callback function returns an
+	// [QueuedQuery.Query], [QueuedQuery.QueryRow], or [QueuedQuery.Exec] will be called. If a callback function returns an
 	// error or the batch encounters an error subsequent callback functions will not be called.
 	//
 	// For simple batch inserts inside a transaction or similar queries, it's sufficient to not set any callbacks,

conn.go

@@ -17,8 +17,8 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
-// ConnConfig contains all the options used to establish a connection. It must be created by ParseConfig and
-// then it can be modified. A manually initialized ConnConfig will cause ConnectConfig to panic.
+// ConnConfig contains all the options used to establish a connection. It must be created by [ParseConfig] and
+// then it can be modified. A manually initialized ConnConfig will cause [ConnectConfig] to panic.
 type ConnConfig struct {
 	pgconn.Config
 
@@ -37,8 +37,8 @@ type ConnConfig struct {
 
 	// DefaultQueryExecMode controls the default mode for executing queries. By default pgx uses the extended protocol
 	// and automatically prepares and caches prepared statements. However, this may be incompatible with proxies such as
-	// PGBouncer. In this case it may be preferable to use QueryExecModeExec or QueryExecModeSimpleProtocol. The same
-	// functionality can be controlled on a per query basis by passing a QueryExecMode as the first query argument.
+	// PGBouncer. In this case it may be preferable to use [QueryExecModeExec] or [QueryExecModeSimpleProtocol]. The same
+	// functionality can be controlled on a per query basis by passing a [QueryExecMode] as the first query argument.
 	DefaultQueryExecMode QueryExecMode
 
 	createdByParseConfig bool // Used to enforce created by ParseConfig rule.
@@ -131,7 +131,7 @@ var (
 )
 
 // Connect establishes a connection with a PostgreSQL server with a connection string. See
-// pgconn.Connect for details.
+// [pgconn.Connect] for details.
 func Connect(ctx context.Context, connString string) (*Conn, error) {
 	connConfig, err := ParseConfig(connString)
 	if err != nil {
@@ -141,7 +141,7 @@ func Connect(ctx context.Context, connString string) (*Conn, error) {
 }
 
 // ConnectWithOptions behaves exactly like Connect with the addition of options. At the present options is only used to
-// provide a GetSSLPassword function.
+// provide a [pgconn.GetSSLPasswordFunc] function.
 func ConnectWithOptions(ctx context.Context, connString string, options ParseConfigOptions) (*Conn, error) {
 	connConfig, err := ParseConfigWithOptions(connString, options)
 	if err != nil {
@@ -151,7 +151,7 @@ func ConnectWithOptions(ctx context.Context, connString string, options ParseCon
 }
 
 // ConnectConfig establishes a connection with a PostgreSQL server with a configuration struct.
-// connConfig must have been created by ParseConfig.
+// connConfig must have been created by [ParseConfig].
 func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error) {
 	// In general this improves safety. In particular avoid the config.Config.OnNotification mutation from affecting other
 	// connections with the same config. See https://github.com/jackc/pgx/issues/618.
@@ -160,8 +160,8 @@ func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error) {
 	return connect(ctx, connConfig)
 }
 
-// ParseConfigWithOptions behaves exactly as ParseConfig does with the addition of options. At the present options is
-// only used to provide a GetSSLPassword function.
+// ParseConfigWithOptions behaves exactly as [ParseConfig] does with the addition of options. At the present options is
+// only used to provide a [pgconn.GetSSLPasswordFunc] function.
 func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*ConnConfig, error) {
 	config, err := pgconn.ParseConfigWithOptions(connString, options.ParseConfigOptions)
 	if err != nil {
@@ -308,8 +308,8 @@ func (c *Conn) Close(ctx context.Context) error {
 }
 
 // Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These
-// placeholders are referenced positionally as $1, $2, etc. name can be used instead of sql with Query, QueryRow, and
-// Exec to execute the statement. It can also be used with Batch.Queue.
+// placeholders are referenced positionally as $1, $2, etc. name can be used instead of sql with [Conn.Query],
+// [Conn.QueryRow], and [Conn.Exec] to execute the statement. It can also be used with [Batch.Queue].
 //
 // The underlying PostgreSQL identifier for the prepared statement will be name if name != sql or a digest of sql if
 // name == sql.
@@ -933,7 +933,7 @@ func (c *Conn) QueryRow(ctx context.Context, sql string, args ...any) Row {
 }
 
 // SendBatch sends all queued queries to the server at once. All queries are run in an implicit transaction unless
-// explicit transaction control statements are executed. The returned BatchResults must be closed before the connection
+// explicit transaction control statements are executed. The returned [BatchResults] must be closed before the connection
 // is used again.
 //
 // Depending on the QueryExecMode, all queries may be prepared before any are executed. This means that creating a table
@@ -1277,7 +1277,7 @@ func (c *Conn) sanitizeForSimpleQuery(sql string, args ...any) (string, error) {
 	return sanitize.SanitizeSQL(sql, valueArgs...)
 }
 
-// LoadType inspects the database for typeName and produces a pgtype.Type suitable for registration. typeName must be
+// LoadType inspects the database for typeName and produces a [pgtype.Type] suitable for registration. typeName must be
 // the name of a type where the underlying type(s) is already understood by pgx. It is for derived types. In particular,
 // typeName must be one of the following:
 //   - An array type name of a type that is already registered. e.g. "_foo" when "foo" is registered.

copy_from.go

@@ -10,8 +10,8 @@ import (
 	"github.com/jackc/pgx/v5/pgconn"
 )
 
-// CopyFromRows returns a CopyFromSource interface over the provided rows slice
-// making it usable by *Conn.CopyFrom.
+// CopyFromRows returns a [CopyFromSource] interface over the provided rows slice
+// making it usable by [Conn.CopyFrom].
 func CopyFromRows(rows [][]any) CopyFromSource {
 	return &copyFromRows{rows: rows, idx: -1}
 }
@@ -34,8 +34,8 @@ func (ctr *copyFromRows) Err() error {
 	return nil
 }
 
-// CopyFromSlice returns a CopyFromSource interface over a dynamic func
-// making it usable by *Conn.CopyFrom.
+// CopyFromSlice returns a [CopyFromSource] interface over a dynamic func
+// making it usable by [Conn.CopyFrom].
 func CopyFromSlice(length int, next func(int) ([]any, error)) CopyFromSource {
 	return &copyFromSlice{next: next, idx: -1, len: length}
 }
@@ -64,7 +64,7 @@ func (cts *copyFromSlice) Err() error {
 	return cts.err
 }
 
-// CopyFromFunc returns a CopyFromSource interface that relies on nxtf for values.
+// CopyFromFunc returns a [CopyFromSource] interface that relies on nxtf for values.
 // nxtf returns rows until it either signals an 'end of data' by returning row=nil and err=nil,
 // or it returns an error. If nxtf returns an error, the copy is aborted.
 func CopyFromFunc(nxtf func() (row []any, err error)) CopyFromSource {
@@ -91,7 +91,7 @@ func (g *copyFromFunc) Err() error {
 	return g.err
 }
 
-// CopyFromSource is the interface used by *Conn.CopyFrom as the source for copy data.
+// CopyFromSource is the interface used by [Conn.CopyFrom] as the source for copy data.
 type CopyFromSource interface {
 	// Next returns true if there is another row and makes the next row data
 	// available to Values(). When there are no more rows available or an error
@@ -260,8 +260,8 @@ func (ct *copyFrom) buildCopyBuf(buf []byte, sd *pgconn.StatementDescription) (b
 // CopyFrom requires all values use the binary format. A pgtype.Type that supports the binary format must be registered
 // for the type of each column. Almost all types implemented by pgx support the binary format.
 //
-// Even though enum types appear to be strings they still must be registered to use with CopyFrom. This can be done with
-// Conn.LoadType and pgtype.Map.RegisterType.
+// Even though enum types appear to be strings they still must be registered to use with [Conn.CopyFrom]. This can be done with
+// [Conn.LoadType] and [pgtype.Map.RegisterType].
 func (c *Conn) CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error) {
 	ct := &copyFrom{
 		conn:          c,