Minor documentation fixes (#341)

.golangci.yml

@@ -371,30 +371,10 @@ issues:
 
   # Excluding configuration per-path, per-linter, per-text and per-source
   exclude-rules:
-    # Exclude some linters from running on tests files.
-    # - path: _test\.go
-    #   linters:
-    #     - gocyclo
-    #     - errcheck
-    #     - dupl
-    #     - gosec
-
-    # Exclude known linters from partially hard-vendored code,
-    # which is impossible to exclude via "nolint" comments.
-    # - path: internal/hmac/
-    #   text: "weak cryptographic primitive"
-    #   linters:
-    #     - gosec
-
-    # Exclude some staticcheck messages
-    # - linters:
-    #     - staticcheck
-    #   text: "SA9003:"
-
-    # Exclude lll issues for long lines with go:generate
-    # - linters:
-    #     - lll
-    #   source: "^//go:generate "
+    # Exclude doc links
+    - linters:
+        - lll
+      source: "^// \\[.*\\]: http"
 
   # Independently from option `exclude` we use default exclude patterns,
   # it can be disabled by this option. To list all

client.go

@@ -26,20 +26,16 @@ import (
 
 // CreateClient returns a new client. The client connects lazily. Call
 // Client.EnsureConnected() to force a connection.
-func CreateClient(ctx context.Context, opts gelcfg.Options) (*Client, error) { // nolint:gocritic,lll
-	return CreateClientDSN(ctx, "", opts)
+func CreateClient(opts gelcfg.Options) (*Client, error) { // nolint:gocritic,lll
+	return CreateClientDSN("", opts)
 }
 
 // CreateClientDSN returns a new client. See also CreateClient.
 //
-// dsn is either an instance name
-// https://www.edgedb.com/docs/clients/connection
-// or it specifies a single string in the following format:
+// dsn is either an instance name or a [DSN].
 //
-//	gel://user:password@host:port/database?option=value.
-//
-// The following options are recognized: host, port, user, database, password.
-func CreateClientDSN(_ context.Context, dsn string, opts gelcfg.Options) (*Client, error) { // nolint:gocritic,lll
+// [DSN]: https://docs.geldata.com/reference/reference/dsn#ref-dsn
+func CreateClientDSN(dsn string, opts gelcfg.Options) (*Client, error) { // nolint:gocritic,lll
 	pool, err := gel.NewPool(dsn, opts)
 	if err != nil {
 		return nil, err
@@ -71,7 +67,7 @@ func (c *Client) EnsureConnected(ctx context.Context) error {
 }
 
 // Close closes all connections in the client.
-// Calling close blocks until all acquired connections have been released,
+// Calling Close() blocks until all acquired connections have been released,
 // and returns an error if called more than once.
 func (c *Client) Close() error { return c.pool.Close() }
 
@@ -270,19 +266,11 @@ func (c *Client) ExecuteSQL(
 	return gel.FirstError(err, c.pool.Release(conn, err))
 }
 
-// Tx runs a [geltypes.TxBlock] in a transaction retrying failed attempts.
+// Tx runs action in a transaction retrying failed attempts.
 //
-// Retries are governed by retry rules.
-// The default rule can be set with WithRetryRule().
-// For more fine grained control a retry rule can be set
-// for each defined RetryCondition using WithRetryCondition().
-// When a transaction fails but is retryable
-// the rule for the failure condition is used to determine if the transaction
-// should be tried again based on RetryRule.Attempts and the amount of time
-// to wait before retrying is determined by RetryRule.Backoff.
-// If either field is unset (see RetryRule) then the default rule is used.
-// If the object's default is unset the fall back is 3 attempts
-// and exponential backoff.
+// Retries are governed by [gelcfg.RetryOptions] and [gelcfg.RetryRule].
+// retry options can be set using [Client.WithRetryOptions].
+// See [gelcfg.RetryRule] for more details on how they work.
 func (c *Client) Tx(ctx context.Context, action geltypes.TxBlock) error {
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {

client_test.go

@@ -32,7 +32,7 @@ import (
 
 func TestConnectClient(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, opts)
+	p, err := CreateClient(opts)
 	require.NoError(t, err)
 
 	var result string
@@ -56,7 +56,7 @@ func TestConnectClient(t *testing.T) {
 
 func TestClientRejectsTransaction(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, opts)
+	p, err := CreateClient(opts)
 	require.NoError(t, err)
 
 	expected := "gel.DisabledCapabilityError: " +
@@ -87,7 +87,7 @@ func TestConnectClientZeroConcurrency(t *testing.T) {
 	o.Concurrency = 0
 
 	ctx := context.Background()
-	p, err := CreateClient(ctx, o)
+	p, err := CreateClient(o)
 	require.NoError(t, err)
 	require.NoError(t, p.EnsureConnected(ctx))
 
@@ -108,8 +108,7 @@ func TestConnectClientZeroConcurrency(t *testing.T) {
 }
 
 func TestCloseClientConcurently(t *testing.T) {
-	ctx := context.Background()
-	p, err := CreateClient(ctx, opts)
+	p, err := CreateClient(opts)
 	require.NoError(t, err)
 
 	errs := make(chan error)
@@ -130,7 +129,7 @@ func TestCloseClientConcurently(t *testing.T) {
 func TestClientTx(t *testing.T) {
 	ctx := context.Background()
 
-	p, err := CreateClient(ctx, opts)
+	p, err := CreateClient(opts)
 	require.NoError(t, err)
 	defer p.Close() // nolint:errcheck
 

connect_test.go

@@ -33,7 +33,7 @@ import (
 
 func TestAuth(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, gelcfg.Options{
+	p, err := CreateClient(gelcfg.Options{
 		Host:       opts.Host,
 		Port:       opts.Port,
 		User:       "user_with_password",
@@ -118,7 +118,7 @@ func convertUint16ToUint8(value uint16) (uint8, uint8) {
 
 func TestConnectTimeout(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, gelcfg.Options{
+	p, err := CreateClient(gelcfg.Options{
 		Host:               opts.Host,
 		Port:               opts.Port,
 		User:               opts.User,
@@ -148,7 +148,7 @@ func TestConnectTimeout(t *testing.T) {
 
 func TestConnectRefused(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, gelcfg.Options{
+	p, err := CreateClient(gelcfg.Options{
 		Host:               "localhost",
 		Port:               23456,
 		WaitUntilAvailable: 1 * time.Nanosecond,
@@ -173,7 +173,7 @@ func TestConnectRefused(t *testing.T) {
 
 func TestConnectInvalidName(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, gelcfg.Options{
+	p, err := CreateClient(gelcfg.Options{
 		Host:               "invalid.example.org",
 		Port:               23456,
 		WaitUntilAvailable: 1 * time.Nanosecond,
@@ -208,7 +208,7 @@ func TestConnectInvalidName(t *testing.T) {
 
 func TestConnectRefusedUnixSocket(t *testing.T) {
 	ctx := context.Background()
-	p, err := CreateClient(ctx, gelcfg.Options{
+	p, err := CreateClient(gelcfg.Options{
 		Host:               "/tmp/non-existent",
 		WaitUntilAvailable: 1 * time.Nanosecond,
 	})

doc.go

@@ -56,8 +56,8 @@
 //
 // You may also connect to a database using a DSN:
 //
-//	url := "gel://edgedb@localhost/edgedb"
-//	client, err := gel.CreateClientDSN(ctx, url, opts)
+//	dsn := "gel://edgedb@localhost/edgedb"
+//	client, err := gel.CreateClientDSN(ctx, dsn, opts)
 //
 // Or you can use Option fields.
 //
@@ -73,7 +73,7 @@
 //
 // gel never returns underlying errors directly.
 // If you are checking for things like context expiration
-// use errors.Is() or errors.As().
+// use [errors.Is] or [errors.As].
 //
 //	err := client.Query(...)
 //	if errors.Is(err, context.Canceled) { ... }
@@ -91,7 +91,7 @@
 // # Datatypes
 //
 // The following list shows the marshal/unmarshal
-// mapping between Gel types and go types:
+// mapping between Gel types and go types. See also [geltypes]:
 //
 //	Gel                      Go
 //	---------                ---------
@@ -128,7 +128,7 @@
 // one directly to the other.
 //
 // Shape fields that are not required must use optional types for receiving
-// query results. The gelcfg.Optional struct can be embedded to make structs
+// query results. The [gelcfg.Optional] struct can be embedded to make structs
 // optional.
 //
 //	type User struct {
@@ -171,9 +171,9 @@
 // # Custom Marshalers
 //
 // Interfaces for user defined marshaler/unmarshalers  are documented in the
-// internal/marshal package.
+// [github.com/geldata/gel-go/internal/marshal] package.
 //
-// [Gel]: https://www.edgedb.com
-// [json]: https://www.edgedb.com/docs/edgeql/insert#bulk-inserts
-// [client connection docs]: https://www.edgedb.com/docs/clients/connection
+// [Gel]: https://www.geldata.com
+// [json]: https://docs.geldata.com/reference/edgeql/insert#bulk-inserts
+// [client connection docs]: https://docs.geldata.com/learn/clients#connection
 package gel

doc_test.go

@@ -36,7 +36,7 @@ type User struct {
 func Example() {
 	opts := gelcfg.Options{Concurrency: 4}
 	ctx := context.Background()
-	db, err := gel.CreateClientDSN(ctx, "gel://edgedb@localhost/test", opts)
+	db, err := gel.CreateClientDSN("gel://edgedb@localhost/test", opts)
 	if err != nil {
 		log.Fatal(err)
 	}

gelcfg/options.go

@@ -29,7 +29,7 @@ import (
 // promote warnings to errors by returning them etc.
 type WarningHandler = func([]error) error
 
-// LogWarnings is a gelcfg.WarningHandler that logs warnings.
+// LogWarnings is a [WarningHandler] that logs warnings.
 func LogWarnings(errors []error) error {
 	for _, err := range errors {
 		log.Println("Gel warning:", err.Error())
@@ -38,7 +38,7 @@ func LogWarnings(errors []error) error {
 	return nil
 }
 
-// WarningsAsErrors is a gelcfg.WarningHandler that returns warnings as
+// WarningsAsErrors is a [WarningHandler] that returns warnings as
 // errors.
 func WarningsAsErrors(warnings []error) error {
 	return errors.Join(warnings...)

gelcfg/queryoptions.go

@@ -22,7 +22,7 @@ func NewQueryOptions() QueryOptions {
 	return QueryOptions{fromFactory: true}
 }
 
-// QueryOptions controls some limitations that the server can impose on
+// QueryOptions controls limitations that the server can impose on
 // queries.
 type QueryOptions struct {
 	fromFactory bool

gelcfg/retryoptions.go

@@ -24,11 +24,9 @@ import (
 )
 
 // RetryCondition represents scenarios that can cause a transaction
-// run in Tx() methods to be retried.
+// or a single query run outside a geltypes.TxBlock to be retried.
 type RetryCondition int
 
-// The following conditions can be configured with a custom RetryRule.
-// See RetryOptions.
 const (
 	// TxConflict indicates that the server could not complete a transaction
 	// because it encountered a deadlock or serialization error.
@@ -39,14 +37,14 @@ const (
 	NetworkError
 )
 
-// NewRetryOptions returns the default retry options.
+// NewRetryOptions returns the default RetryOptions.
 func NewRetryOptions() RetryOptions {
 	return RetryOptions{fromFactory: true}.WithDefault(NewRetryRule())
 }
 
-// RetryOptions configures how Tx() retries failed transactions.  Use
-// NewRetryOptions to get a default RetryOptions value instead of creating one
-// yourself.
+// RetryOptions configures how failed transactions or queries outside of
+// transactions are retried.  Use [NewRetryOptions] to get a default
+// RetryOptions value instead of creating one yourself.
 type RetryOptions struct {
 	fromFactory bool
 	txConflict  RetryRule

gelcfg/retryrule.go

@@ -27,7 +27,7 @@ import (
 var rnd = snc.NewRand()
 
 // RetryBackoff returns the duration to wait after the nth attempt
-// before making the next attempt when retrying a transaction.
+// before retrying a transaction.
 type RetryBackoff func(n int) time.Duration
 
 func defaultBackoff(attempt int) time.Duration {

gelcfg/txoptions.go

@@ -18,8 +18,9 @@ package gelcfg
 
 import "fmt"
 
-// IsolationLevel documentation can be found here
-// https://www.edgedb.com/docs/reference/edgeql/tx_start#parameters
+// IsolationLevel documentation can be found [here]
+//
+// [here]: https://docs.geldata.com/reference/stdlib/sys#type::sys::TransactionIsolation
 type IsolationLevel string
 
 const (

options.go

@@ -52,7 +52,12 @@ func (c *Client) copyPool() {
 	c.pool = &pool
 }
 
-// WithConfig sets configuration values for the returned client.
+// WithConfig returns a shallow copy of the client
+// with configuration values set to cfg.
+// Equivalent to using the edgeql configure session command.
+// For available configuration parameters refer to the [Config documentation].
+//
+// [Config documentation]: https://docs.geldata.com/reference/stdlib/cfg#ref-std-cfg
 func (c Client) WithConfig( // nolint:gocritic
 	cfg map[string]interface{},
 ) *Client {
@@ -75,7 +80,8 @@ func (c Client) WithConfig( // nolint:gocritic
 	return &c
 }
 
-// WithoutConfig unsets configuration values for the returned client.
+// WithoutConfig returns a shallow copy of the client
+// with keys unset from the configuration.
 func (c Client) WithoutConfig(key ...string) *Client { // nolint:gocritic
 	state := gel.CopyState(c.pool.State)
 
@@ -91,7 +97,8 @@ func (c Client) WithoutConfig(key ...string) *Client { // nolint:gocritic
 	return &c
 }
 
-// WithModuleAliases sets module name aliases for the returned client.
+// WithModuleAliases returns a shallow copy of the client
+// with module name aliases set to aliases.
 func (c Client) WithModuleAliases( // nolint:gocritic
 	aliases ...gelcfg.ModuleAlias,
 ) *Client {
@@ -112,7 +119,8 @@ func (c Client) WithModuleAliases( // nolint:gocritic
 	return &c
 }
 
-// WithoutModuleAliases unsets module name aliases for the returned client.
+// WithoutModuleAliases returns a shallow copy of the client
+// with aliases unset.
 func (c Client) WithoutModuleAliases( // nolint:gocritic
 	aliases ...string,
 ) *Client {
@@ -193,7 +201,7 @@ func (c Client) WithWarningHandler( // nolint:gocritic
 	return &c
 }
 
-// WithQueryOptions sets the gelcfg.Queryoptions for the returned Client.
+// WithQueryOptions sets the [gelcfg.QueryOptions] for the returned Client.
 func (c Client) WithQueryOptions(
 	options gelcfg.QueryOptions,
 ) *Client { // nolint:gocritic

testserver_test.go

@@ -138,9 +138,8 @@ func initClient() {
 	opts = testserver.Options()
 
 	log.Println("initializing testserver.Client")
-	ctx := context.Background()
 	var err error
-	client, err = CreateClient(ctx, opts)
+	client, err = CreateClient(opts)
 	if err != nil {
 		testserver.Fatal(err)
 	}

tutorial_test.go

@@ -47,7 +47,6 @@ func TestTutorial(t *testing.T) {
 	require.NoError(t, err)
 
 	edb, err := CreateClient(
-		ctx,
 		gelcfg.Options{
 			Host:       opts.Host,
 			Port:       opts.Port,