From 7315ffdbf20cbff04b02f9a19db845e8cd42a4fe Mon Sep 17 00:00:00 2001
From: fmoor <fmoor@gmx.com>
Date: Thu, 3 Nov 2022 10:41:12 -0700
Subject: [PATCH] Update documentation

---
 internal/client/doc.go => doc.go           | 21 ++++++++++++++--
 internal/client/doc_test.go => doc_test.go |  0
 internal/client/transaction_test.go        | 18 --------------
 tx_test.go                                 | 28 ++++++++++++++++++++++
 4 files changed, 47 insertions(+), 20 deletions(-)
 rename internal/client/doc.go => doc.go (84%)
 rename internal/client/doc_test.go => doc_test.go (100%)
 create mode 100644 tx_test.go

diff --git a/internal/client/doc.go b/doc.go
similarity index 84%
rename from internal/client/doc.go
rename to doc.go
index 8f783317..6043a276 100644
--- a/internal/client/doc.go
+++ b/doc.go
@@ -14,7 +14,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package edgedb is the official Go EdgeDB driver. https://www.edgedb.com
+// Package edgedb is the official Go driver for [EdgeDB].
 //
 // Typical usage looks like this:
 //
@@ -48,7 +48,10 @@
 //	    ...
 //	}
 //
-// You can also connect to a database using a DSN:
+// We recommend using environment variables for connection parameters. See the
+// [client connection docs] for more information.
+//
+// You may also connect to a database using a DSN:
 //
 //	url := "edgedb://edgedb@localhost/edgedb"
 //	client, err := edgedb.CreateClientDSN(ctx, url, opts)
@@ -135,8 +138,22 @@
 //	fmt.Println(result.Missing())
 //	// Output: false
 //
+// Not all types listed above are valid query parameters.  To pass a slice of
+// scalar values use array in your query. EdgeDB doesn't currently support
+// using sets as parameters.
+//
+//	query := `select User filter .id in array_unpack(<array<uuid>>$1)`
+//	client.QuerySingle(ctx, query, $user, []edgedb.UUID{...})
+//
+// Nested structures are also not directly allowed but you can use [json]
+// instead.
+//
 // # Custom Marshalers
 //
 // Interfaces for user defined marshaler/unmarshalers  are documented in the
 // internal/marshal package.
+//
+// [EdgeDB]: https://www.edgedb.com
+// [json]: https://www.edgedb.com/docs/edgeql/insert#bulk-inserts
+// [client connection docs]: https://www.edgedb.com/docs/clients/connection
 package edgedb
diff --git a/internal/client/doc_test.go b/doc_test.go
similarity index 100%
rename from internal/client/doc_test.go
rename to doc_test.go
diff --git a/internal/client/transaction_test.go b/internal/client/transaction_test.go
index 0f556526..7238d621 100644
--- a/internal/client/transaction_test.go
+++ b/internal/client/transaction_test.go
@@ -20,7 +20,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"log"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -157,20 +156,3 @@ func TestTxKinds(t *testing.T) {
 		})
 	}
 }
-
-// Transactions can be executed using the Tx() method. Note that queries are
-// executed on the Tx object. Queries executed on the client in a transaction
-// callback will not run in the transaction and will be applied immediately. In
-// edgedb-go the callback may be re-run if any of the queries fail in a way
-// that might succeed on subsequent attempts. Transaction behavior can be
-// configured with TxOptions and the retrying behavior can be configured with
-// RetryOptions.
-func ExampleTx() {
-	ctx := context.Background()
-	err := client.Tx(ctx, func(ctx context.Context, tx *Tx) error {
-		return tx.Execute(ctx, "INSERT User { name := 'Don' }")
-	})
-	if err != nil {
-		log.Println(err)
-	}
-}
diff --git a/tx_test.go b/tx_test.go
new file mode 100644
index 00000000..e8d3b4c5
--- /dev/null
+++ b/tx_test.go
@@ -0,0 +1,28 @@
+package edgedb_test
+
+import (
+	"context"
+	"log"
+
+	edgedb "github.com/edgedb/edgedb-go/internal/client"
+)
+
+// Transactions can be executed using the Tx() method. Note that queries are
+// executed on the Tx object. Queries executed on the client in a transaction
+// callback will not run in the transaction and will be applied immediately. In
+// edgedb-go the callback may be re-run if any of the queries fail in a way
+// that might succeed on subsequent attempts. Transaction behavior can be
+// configured with TxOptions and the retrying behavior can be configured with
+// RetryOptions.
+func ExampleTx() {
+	ctx := context.Background()
+	client, err := edgedb.CreateClient(ctx, edgedb.Options{})
+
+	err = client.Tx(ctx, func(ctx context.Context, tx *edgedb.Tx) error {
+		return tx.Execute(ctx, "INSERT User { name := 'Don' }")
+	})
+
+	if err != nil {
+		log.Println(err)
+	}
+}