docs: add comments to all samples to document what they do and how to…

… use them (#46)

* docs: add comments to all samples to document what they do and how to use them

* fix: typos

examples/emulator_runner.go

@@ -34,6 +34,14 @@ import (
 var cli *client.Client
 var containerId string
 
+// RunSampleOnEmulator will run a sample function against a Spanner emulator instance in a Docker container.
+// It requires Docker to be installed your local system to work.
+//
+// It will execute the following steps:
+// 1. Start a Spanner emulator in a Docker container.
+// 2. Create a sample instance and database on the emulator.
+// 3. Execute the sample function against the emulator.
+// 4. Stop the Docker container with the emulator.
 func RunSampleOnEmulator(sample func(string, string, string) error, ddlStatements ...string) {
 	var err error
 	if err = startEmulator(); err != nil {

examples/helloworld/main.go

@@ -23,6 +23,9 @@ import (
 	"github.com/cloudspannerecosystem/go-sql-spanner/examples"
 )
 
+// Simple sample application that shows how to use the Spanner Go sql driver.
+//
+// Execute the sample with the command `go run main.go` from this directory.
 func helloWorld(projectId, instanceId, databaseId string) error {
 	ctx := context.Background()
 	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))

examples/mutations/main.go

@@ -27,6 +27,10 @@ import (
 
 var createTableStatement = "CREATE TABLE Singers (SingerId INT64, Name STRING(MAX)) PRIMARY KEY (SingerId)"
 
+// Example that shows how to use Mutations to insert data in a Cloud Spanner database using the Go sql driver.
+// Mutations can be more efficient than DML statements for bulk insert/update operations.
+//
+// Execute the sample with the command `go run main.go` from this directory.
 func mutations(projectId, instanceId, databaseId string) error {
 	ctx := context.Background()
 	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))

examples/stale-reads/main.go

@@ -26,6 +26,17 @@ import (
 
 var createTableStatement = "CREATE TABLE Singers (SingerId INT64, Name STRING(MAX)) PRIMARY KEY (SingerId)"
 
+// Example for executing read-only transactions with a different timestamp bound than Strong. Both single-use and
+// multi-use read-only transactions can be set up to use a different timestamp bound by executing a
+// `SET READ_ONLY_STALENESS=<staleness>` statement before executing the read-only transaction. `<staleness>` must
+// be one of the following:
+//
+// 'READ_TIMESTAMP yyyy-mm-ddTHH:mi:ssZ'
+// 'MIN_READ_TIMESTAMP yyyy-mm-ddTHH:mi:ssZ' (only for single queries outside a multi-use read-only transaction)
+// 'EXACT_STALENESS <int64>s|ms|us|ns' (example: 'EXACT_STALENESS 10s' for 10 seconds)
+// 'MAX_STALENESS <int64>s|ms|us|ns' (only for single queries outside a multi-use read-only transaction)
+//
+// Execute the sample with the command `go run main.go` from this directory.
 func staleReads(projectId, instanceId, databaseId string) error {
 	ctx := context.Background()
 	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))

examples/transactions/main.go

@@ -25,6 +25,9 @@ import (
 
 var createTableStatement = "CREATE TABLE Singers (SingerId INT64, Name STRING(MAX)) PRIMARY KEY (SingerId)"
 
+// Example for executing a read/write transaction on a Google Cloud Spanner database.
+//
+// Execute the sample with the command `go run main.go` from this directory.
 func transaction(projectId, instanceId, databaseId string) error {
 	ctx := context.Background()
 	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))