fix(docs): add an operation polling example (#2186)

noahdietz · web-flow · commit bd12ebaeb0a5 · 2023-09-25T13:55:14.000-07:00
diff --git 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
