docs: move example inline into godoc (#4626)

This change is needed, at least temporarily, to facilitate the
splitting of modules. The parent module can't depend on a module
that is about to be split out as tidying will fail to resolve
import paths as the code no longer exists.

doc.go

@@ -28,18 +28,96 @@ Authentication and Authorization
 
 All the clients in sub-packages support authentication via Google Application Default
 Credentials (see https://cloud.google.com/docs/authentication/production), or
-by providing a JSON key file for a Service Account. See the authentication examples
-in this package for details.
+by providing a JSON key file for a Service Account. See examples below.
+
+Google Application Default Credentials (ADC) is the recommended way to authorize
+and authenticate clients. For information on how to create and obtain
+Application Default Credentials, see
+https://cloud.google.com/docs/authentication/production. Here is an example
+of a client using ADC to authenticate:
+ client, err := secretmanager.NewClient(context.Background())
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ _ = client // Use the client.
+
+You can use a file with credentials to authenticate and authorize, such as a JSON
+key file associated with a Google service account. Service Account keys can be
+created and downloaded from
+https://console.cloud.google.com/iam-admin/serviceaccounts. This example uses
+the Secret Manger client, but the same steps apply to the other client libraries
+underneath this package. Example:
+ client, err := secretmanager.NewClient(context.Background(),
+ 	option.WithCredentialsFile("/path/to/service-account-key.json"))
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ _ = client // Use the client.
+
+In some cases (for instance, you don't want to store secrets on disk), you can
+create credentials from in-memory JSON and use the WithCredentials option.
+The google package in this example is at golang.org/x/oauth2/google.
+This example uses the Secret Manager client, but the same steps apply to
+the other client libraries underneath this package. Note that scopes can be
+found at https://developers.google.com/identity/protocols/oauth2/scopes, and
+are also provided in all auto-generated libraries: for example,
+cloud.google.com/go/secretmanager/apiv1 provides DefaultAuthScopes. Example:
+ ctx := context.Background()
+ creds, err := google.CredentialsFromJSON(ctx, []byte("JSON creds"), secretmanager.DefaultAuthScopes()...)
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ client, err := secretmanager.NewClient(ctx, option.WithCredentials(creds))
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ _ = client // Use the client.
 
 
 Timeouts and Cancellation
 
 By default, non-streaming methods, like Create or Get, will have a default deadline applied to the
 context provided at call time, unless a context deadline is already set. Streaming
 methods have no default deadline and will run indefinitely. To set timeouts or
-arrange for cancellation, use contexts. See the examples for details. Transient
+arrange for cancellation, use contexts. Transient
 errors will be retried when correctness allows.
 
+Here is an example of how to set a timeout for an RPC, use context.WithTimeout:
+ ctx := context.Background()
+ // Do not set a timeout on the context passed to NewClient: dialing happens
+ // asynchronously, and the context is used to refresh credentials in the
+ // background.
+ client, err := secretmanager.NewClient(ctx)
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ // Time out if it takes more than 10 seconds to create a dataset.
+ tctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+ defer cancel() // Always call cancel.
+
+ req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/project-id/secrets/name"}
+ if err := client.DeleteSecret(tctx, req); err != nil {
+ 	// TODO: handle error.
+ }
+
+Here is an example of how to arrange for an RPC to be canceled, use context.WithCancel:
+ ctx := context.Background()
+ // Do not cancel the context passed to NewClient: dialing happens asynchronously,
+ // and the context is used to refresh credentials in the background.
+ client, err := secretmanager.NewClient(ctx)
+ if err != nil {
+ 	// TODO: handle error.
+ }
+ cctx, cancel := context.WithCancel(ctx)
+ defer cancel() // Always call cancel.
+
+ // TODO: Make the cancel function available to whatever might want to cancel the
+ // call--perhaps a GUI button.
+ req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/proj/secrets/name"}
+ if err := client.DeleteSecret(cctx, req); err != nil {
+ 	// TODO: handle error.
+ }
+
 To opt out of default deadlines, set the temporary environment variable
 GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE to "true" prior to client
 creation. This affects all Google Cloud Go client libraries. This opt-out