Add docs for pagers and pollers (Azure#17840)

* Add docs for pagers and pollers

* a few tweaks

* feedback

Author: jhendrixMSFT

sdk/azcore/doc.go

@@ -6,7 +6,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-Package azcore implements an HTTP request/response middleware pipeline.
+Package azcore implements an HTTP request/response middleware pipeline used by Azure SDK clients.
 
 The middleware consists of three components.
 
@@ -114,7 +114,7 @@ The flow of Request and Response looks like the following:
 
    policy.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+
                                                                       |
-                                                               HTTP(s) endpoint
+                                                               HTTP(S) endpoint
                                                                       |
    caller <--------- PolicyA <- PolicyB <- PolicyC <- http.Response-+
 
@@ -152,13 +152,13 @@ a means to resolve the ambiguity between a field to be excluded and its zero-val
 In the above example, Name and Count are defined as pointer-to-type to disambiguate between
 a missing value (nil) and a zero-value (0) which might have semantic differences.
 
-In a PATCH operation, any fields left as `nil` are to have their values preserved.  When updating
+In a PATCH operation, any fields left as nil are to have their values preserved.  When updating
 a Widget's count, one simply specifies the new value for Count, leaving Name nil.
 
 To fulfill the requirement for sending a JSON null, the NullValue() function can be used.
 
    w := Widget{
-      Count: azcore.NullValue(0).(*int),
+      Count: azcore.NullValue[*int](),
    }
 
 This sends an explict "null" for Count, indicating that any current value for Count should be deleted.
@@ -177,5 +177,81 @@ a callback that writes to the desired location.  Any custom logging implementati
 own synchronization to handle concurrent invocations.
 
 See the docs for the log package for further details.
+
+Pageable Operations
+
+Pageable operations return potentially large data sets spread over multiple GET requests.  The result of
+each GET is a "page" of data consisting of a slice of items.
+
+Pageable operations can be identified by their New*Pager naming convention and return type of *runtime.Pager[T].
+
+   func (c *WidgetClient) NewListWidgetsPager(o *Options) *runtime.Pager[PageResponse]
+
+The call to WidgetClient.NewListWidgetsPager() returns an instance of *runtime.Pager[T] for fetching pages
+and determining if there are more pages to fetch.  No IO calls are made until the NextPage() method is invoked.
+
+   pager := widgetClient.NewListWidgetsPager(nil)
+   for pager.More() {
+      page, err := pager.NextPage(context.TODO())
+      // handle err
+      for _, widget := range page.Values {
+         // process widget
+      }
+   }
+
+Long-Running Operations
+
+Long-running operations (LROs) are operations consisting of an initial request to start the operation followed
+by polling to determine when the operation has reached a terminal state.  An LRO's terminal state is one
+of the following values.
+
+   * Succeeded - the LRO completed successfully
+   *    Failed - the LRO failed to complete
+   *  Canceled - the LRO was canceled
+
+LROs can be identified by their Begin* prefix and their return type of *runtime.Poller[T].
+
+   func (c *WidgetClient) BeginCreateOrUpdate(ctx context.Context, w Widget, o *Options) (*runtime.Poller[Response], error)
+
+When a call to WidgetClient.BeginCreateOrUpdate() returns a nil error, it means that the LRO has started.
+It does _not_ mean that the widget has been created or updated (or failed to be created/updated).
+
+The *runtime.Poller[T] provides APIs for determining the state of the LRO.  To wait for the LRO to complete,
+call the PollUntilDone() method.
+
+   poller, err := widgetClient.BeginCreateOrUpdate(context.TODO(), Widget{}, nil)
+   // handle err
+   result, err := poller.PollUntilDone(context.TODO(), nil)
+   // handle err
+   // use result
+
+The call to PollUntilDone() will block the current goroutine until the LRO has reached a terminal state or the
+context is canceled/timed out.
+
+Note that LROs can take anywhere from several seconds to several minutes.  The duration is operation-dependent.  Due to
+this variant behavior, pollers do _not_ have a preconfigured time-out.  Use a context with the appropriate cancellation
+mechanism as required.
+
+Resume Tokens
+
+Pollers provide the ability to serialize their state into a "resume token" which can be used by another process to
+recreate the poller.  This is achieved via the runtime.Poller[T].ResumeToken() method.
+
+   token, err := poller.ResumeToken()
+   // handle error
+
+Note that a token can only be obtained for a poller that's in a non-terminal state.  Also note that any subsequent calls
+to poller.Poll() might change the poller's state.  In this case, a new token should be created.
+
+After the token has been obtained, it can be used to recreate an instance of the originating poller.
+
+   poller, err := widgetClient.BeginCreateOrUpdate(nil, Widget{}, &Options{
+      ResumeToken: token,
+   })
+
+When resuming a poller, no IO is performed, and zero-value arguments can be used for everything but the Options.ResumeToken.
+
+Resume tokens are unique per service client and operation.  Attempting to resume a poller for LRO BeginB() with a token from LRO
+BeginA() will result in an error.
 */
 package azcore