GODRIVER-1259 Add WithTransaction example for docs site (#370)

- Also addresses GODRIVER-1541

Author: Divjot Arora

examples/documentation_examples/examples.go

@@ -11,6 +11,7 @@ package documentation_examples
 
 import (
 	"context"
+	"fmt"
 	"io/ioutil"
 	logger "log"
 	"sync/atomic"
@@ -1937,6 +1938,60 @@ func TransactionsExamples(ctx context.Context, client *mongo.Client) error {
 
 // End Transactions Retry Example 3
 
+// Start Transactions withTxn API Example 1
+
+// WithTransactionExample is an example of using the Session.WithTransaction function.
+func WithTransactionExample() {
+	ctx := context.Background()
+	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
+	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
+	// For a sharded cluster, connect to the mongos instances; e.g.
+	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
+	var uri string
+
+	clientOpts := options.Client().ApplyURI(uri)
+	client, err := mongo.Connect(ctx, clientOpts)
+	if err != nil {
+		panic(err)
+	}
+	defer func() { _ = client.Disconnect(ctx) }()
+
+	// Prereq: Create collections.
+	wcMajority := writeconcern.New(writeconcern.WMajority(), writeconcern.WTimeout(1*time.Second))
+	wcMajorityCollectionOpts := options.Collection().SetWriteConcern(wcMajority)
+	fooColl := client.Database("mydb1").Collection("foo", wcMajorityCollectionOpts)
+	barColl := client.Database("mydb1").Collection("bar", wcMajorityCollectionOpts)
+
+	// Step 1: Define the callback that specifies the sequence of operations to perform inside the transaction.
+	callback := func(sessCtx mongo.SessionContext) (interface{}, error) {
+		// Important: You must pass sessCtx as the Context parameter to the operations for them to be executed in the
+		// transaction.
+		if _, err := fooColl.InsertOne(sessCtx, bson.D{{"abc", 1}}); err != nil {
+			return nil, err
+		}
+		if _, err := barColl.InsertOne(sessCtx, bson.D{{"xyz", 999}}); err != nil {
+			return nil, err
+		}
+
+		return nil, nil
+	}
+
+	// Step 2: Start a session and run the callback using WithTransaction.
+	session, err := client.StartSession()
+	if err != nil {
+		panic(err)
+	}
+	defer session.EndSession(ctx)
+
+	result, err := session.WithTransaction(ctx, callback)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("result: %v\n", result)
+}
+
+// End Transactions withTxn API Example 1
+
 // ChangeStreamExamples contains examples of changestream operations.
 func ChangeStreamExamples(t *testing.T, db *mongo.Database) {
 	ctx := context.Background()