transport: expand on package documentation, add basic examples
Change-Id: Id0a680f2af20d1dda30ba37f0a9d5187799169cb
Reviewed-on: https://code-review.googlesource.com/c/38090
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Tyler Bui-Palsulich <tbp@google.com>
diff --git a/transport/dial.go b/transport/dial.go
index cf1ffca..1fb7cf9 100644
--- a/transport/dial.go
+++ b/transport/dial.go
@@ -12,9 +12,6 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package transport supports network connections to HTTP and GRPC servers.
-// This package is not intended for use by end developers. Use the
-// google.golang.org/api/option package to configure API clients.
package transport
import (
diff --git a/transport/doc.go b/transport/doc.go
new file mode 100644
index 0000000..4915036
--- /dev/null
+++ b/transport/doc.go
@@ -0,0 +1,21 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package transport provides utility methods for creating authenticated
+// transports to Google's HTTP and gRPC APIs. It is intended to be used in
+// conjunction with google.golang.org/api/option.
+//
+// This package is not intended for use by end developers. Use the
+// google.golang.org/api/option package to configure API clients.
+package transport
diff --git a/transport/examples_test.go b/transport/examples_test.go
new file mode 100644
index 0000000..bd199bf
--- /dev/null
+++ b/transport/examples_test.go
@@ -0,0 +1,52 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package transport_test
+
+import (
+ "context"
+ "log"
+
+ "google.golang.org/api/option"
+ "google.golang.org/api/transport"
+)
+
+func Example_applicationDefaultCredentials() {
+ ctx := context.Background()
+
+ // Providing no auth option will cause NewClient to look for Application
+ // Default Creds as specified at https://godoc.org/golang.org/x/oauth2/google#FindDefaultCredentials.
+ //
+ // Note: Given the same set of options, transport.NewHTTPClient and
+ // transport.NewGRPCClient use the same credentials.
+ c, _, err := transport.NewHTTPClient(ctx)
+ if err != nil {
+ log.Fatal(err)
+ }
+ _ = c // Use authenticated client.
+}
+
+func Example_withCredentialsFile() {
+ ctx := context.Background()
+
+ // Download service account creds per https://cloud.google.com/docs/authentication/end-user.
+ //
+ // Note: Given the same set of options, transport.NewHTTPClient and
+ // transport.NewGRPCClient use the same credentials.
+ c, _, err := transport.NewHTTPClient(ctx, option.WithCredentialsFile("/path/to/service-account-creds.json"))
+ if err != nil {
+ log.Fatal(err)
+ }
+ _ = c // Use authenticated client.
+}
