From bd12ebaeb0a55d37c24881968981058f5a80f15a Mon Sep 17 00:00:00 2001
From: Noah Dietz <noahdietz@users.noreply.github.com>
Date: Mon, 25 Sep 2023 13:55:14 -0700
Subject: [PATCH] fix(docs): add an operation polling example (#2186)

---
 doc.go | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc.go b/doc.go
index 0bce85869b5..3095f42b1e5 100644
--- a/doc.go
+++ b/doc.go
@@ -84,4 +84,51 @@
 //			fmt.Println("Domain: %s", aErr.Domain())
 //		}
 //	}
+//
+// # Polling Operations
+//
+// If an API call returns an Operation, that means it could take some time to
+// complete the work initiated by the API call. Applications that are interested
+// in the end result of the operation they initiated should wait until the
+// Operation.Done field indicates it is finished. To do this, use the service's
+// Operation client, and a loop, like so:
+//
+//   import (
+//		gax "github.com/googleapis/gax-go/v2"
+//   )
+//
+//   // existing application code...
+//
+//   // API call that returns an Operation.
+//	 op, err := myApiClient.CalculateFoo().Do()
+//	 if err != nil {
+//		// handle err
+//	 }
+//
+//	 operationsService = myapi.NewOperationsService(myApiClient)
+//   pollingBackoff := gax.Backoff{
+// 	    Initial:    time.Second,
+// 	    Max:        time.Minute, // Max time between polling attempts.
+// 	    Multiplier: 2,
+//   }
+//	 for {
+//		if op.Done {
+//			break
+//		}
+//		// not done, sleep with backoff, then poll again
+//		if err := gax.Sleep(ctx, pollingBackoff.Pause()); err != nil {
+//			// handle error
+//		}
+//		op, err := operationsService.Get(op.Name).Do()
+//		if err != nil {
+//			// handle error
+//		}
+//	 }
+//
+//	 if op.Error != nil {
+//		// handle operation err
+//	 }
+//
+//	 // Do something with the response
+//	 fmt.Println(op.Response)
 package api