From cce3f19a6352281d7d14016e60f070452e94eab7 Mon Sep 17 00:00:00 2001 From: Frederick Date: Wed, 26 Feb 2025 07:22:08 -0700 Subject: [PATCH] Minor documentation fixes (#341) --- .golangci.yml | 28 ++++------------------------ client.go | 32 ++++++++++---------------------- client_test.go | 11 +++++------ connect_test.go | 10 +++++----- doc.go | 18 +++++++++--------- doc_test.go | 2 +- gelcfg/options.go | 4 ++-- gelcfg/queryoptions.go | 2 +- gelcfg/retryoptions.go | 12 +++++------- gelcfg/retryrule.go | 2 +- gelcfg/txoptions.go | 5 +++-- options.go | 18 +++++++++++++----- testserver_test.go | 3 +-- tutorial_test.go | 1 - tx_test.go | 2 +- 15 files changed, 61 insertions(+), 89 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 760248ee..e0b06fdf 100644 --- a/.golangci.yml +++ b/.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 diff --git a/client.go b/client.go index f89beac1..2d3d1207 100644 --- a/client.go +++ b/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 { diff --git a/client_test.go b/client_test.go index 08c1ea2b..bcf4fbf8 100644 --- a/client_test.go +++ b/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 diff --git a/connect_test.go b/connect_test.go index c5e0fa89..6ea69b2f 100644 --- a/connect_test.go +++ b/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, }) diff --git a/doc.go b/doc.go index f2ff846f..4ecaf109 100644 --- a/doc.go +++ b/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 diff --git a/doc_test.go b/doc_test.go index db9937bf..520dd989 100644 --- a/doc_test.go +++ b/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) } diff --git a/gelcfg/options.go b/gelcfg/options.go index 652de335..0e95571e 100644 --- a/gelcfg/options.go +++ b/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...) diff --git a/gelcfg/queryoptions.go b/gelcfg/queryoptions.go index 2484d5c6..fcddfd04 100644 --- a/gelcfg/queryoptions.go +++ b/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 diff --git a/gelcfg/retryoptions.go b/gelcfg/retryoptions.go index a256ee92..b2462d3d 100644 --- a/gelcfg/retryoptions.go +++ b/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 diff --git a/gelcfg/retryrule.go b/gelcfg/retryrule.go index 6fc6c38e..9af44d4e 100644 --- a/gelcfg/retryrule.go +++ b/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 { diff --git a/gelcfg/txoptions.go b/gelcfg/txoptions.go index 9d92f37b..35d0ef15 100644 --- a/gelcfg/txoptions.go +++ b/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 ( diff --git a/options.go b/options.go index 60d58893..e01ebf10 100644 --- a/options.go +++ b/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 diff --git a/testserver_test.go b/testserver_test.go index 8747b434..d2b54a25 100644 --- a/testserver_test.go +++ b/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) } diff --git a/tutorial_test.go b/tutorial_test.go index c6df805c..6f069ac4 100644 --- a/tutorial_test.go +++ b/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, diff --git a/tx_test.go b/tx_test.go index b945580a..fd5c0965 100644 --- a/tx_test.go +++ b/tx_test.go @@ -34,7 +34,7 @@ import ( // RetryOptions. func ExampleTx() { ctx := context.Background() - client, err := gel.CreateClient(ctx, gelcfg.Options{}) + client, err := gel.CreateClient(gelcfg.Options{}) if err != nil { log.Println(err) }