Skip to content

Commit

Permalink
docs: point more users forward (#2126)
Browse files Browse the repository at this point in the history 
Some users still land on our older libraries first, lets put a similar disclaimer that is in our README into all our generated client godoc.

Also cleaned up some formatting of these package docs.

Internal bug: 288938991
  • Loading branch information
@codyoss
codyoss committed Aug 30, 2023
1 parent fd53dce commit 62d88ff
Show file tree
Hide file tree
Showing 24 changed files with 505 additions and 184 deletions.
111 changes: 66 additions & 45 deletions google-api-go-generator/gen.go
View file
Expand Up @@ -587,6 +587,71 @@ func (a *API) WriteGeneratedCode() error {
return nil
}

func (a *API) printPkgDocs() {
pkg := a.Package()
pn := a.pn

pn("// Package %s provides access to the %s.", pkg, a.doc.Title)
if r := replacementPackage.Get(pkg, a.Version); r != "" {
pn("//")
pn("// This package is DEPRECATED. Use package %s instead.", r)
}
docsLink = a.doc.DocumentationLink
if docsLink != "" {
pn("//")
pn("// For product documentation, see: %s", docsLink)
}
pn("//")
pn("// # Library status")
pn("//")
pn("// These client libraries are officially supported by Google. However, this")
pn("// library is considered complete and is in maintenance mode. This means")
pn("// that we will address critical bugs and security issues but will not add")
pn("// any new features.")
pn("// ")
pn("// When possible, we recommend using our newer")
pn("// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)")
pn("// that are still actively being worked and iterated on.")
pn("//")
pn("// # Creating a client")
pn("//")
pn("// Usage example:")
pn("//")
pn("// import %q", a.Target())
pn("// ...")
pn("// ctx := context.Background()")
pn("// %sService, err := %s.NewService(ctx)", pkg, pkg)
pn("//")
pn("// In this example, Google Application Default Credentials are used for")
pn("// authentication. For information on how to create and obtain Application")
pn("// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.")
pn("//")
pn("// # Other authentication options")
pn("//")
if len(a.doc.Auth.OAuth2Scopes) > 1 {
pn(`// By default, all available scopes (see "Constants") are used to authenticate.`)
pn(`// To restrict scopes, use [google.golang.org/api/option.WithScopes]:`)
pn("//")
// NOTE: the first scope tends to be the broadest. Use the last one to demonstrate restriction.
pn("// %sService, err := %s.NewService(ctx, option.WithScopes(%s.%s))", pkg, pkg, pkg, scopeIdentifier(a.doc.Auth.OAuth2Scopes[len(a.doc.Auth.OAuth2Scopes)-1]))
pn("//")
}
pn("// To use an API key for authentication (note: some APIs do not support API")
pn("// keys), use [google.golang.org/api/option.WithAPIKey]:")
pn("//")
pn(`// %sService, err := %s.NewService(ctx, option.WithAPIKey("AIza..."))`, pkg, pkg)
pn("//")
pn("// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth")
pn("// flow, use [google.golang.org/api/option.WithTokenSource]:")
pn("//")
pn("// config := &oauth2.Config{...}")
pn("// // ...")
pn("// token, err := config.Exchange(ctx, ...)")
pn("// %sService, err := %s.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))", pkg, pkg)
pn("//")
pn("// See [google.golang.org/api/option.ClientOption] for details on options.")
}

var docsLink string

func (a *API) GenerateCode() ([]byte, error) {
Expand Down Expand Up @@ -638,51 +703,7 @@ func (a *API) GenerateCode() ([]byte, error) {
// Code generated file. DO NOT EDIT.
`, *copyrightYear)

pn("// Package %s provides access to the %s.", pkg, a.doc.Title)
if r := replacementPackage.Get(pkg, a.Version); r != "" {
pn("//")
pn("// This package is DEPRECATED. Use package %s instead.", r)
}
docsLink = a.doc.DocumentationLink
if docsLink != "" {
pn("//")
pn("// For product documentation, see: %s", docsLink)
}
pn("//")
pn("// Creating a client")
pn("//")
pn("// Usage example:")
pn("//")
pn("// import %q", a.Target())
pn("// ...")
pn("// ctx := context.Background()")
pn("// %sService, err := %s.NewService(ctx)", pkg, pkg)
pn("//")
pn("// In this example, Google Application Default Credentials are used for authentication.")
pn("//")
pn("// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.")
pn("//")
pn("// Other authentication options")
pn("//")
if len(a.doc.Auth.OAuth2Scopes) > 1 {
pn(`// By default, all available scopes (see "Constants") are used to authenticate. To restrict scopes, use option.WithScopes:`)
pn("//")
// NOTE: the first scope tends to be the broadest. Use the last one to demonstrate restriction.
pn("// %sService, err := %s.NewService(ctx, option.WithScopes(%s.%s))", pkg, pkg, pkg, scopeIdentifier(a.doc.Auth.OAuth2Scopes[len(a.doc.Auth.OAuth2Scopes)-1]))
pn("//")
}
pn("// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:")
pn("//")
pn(`// %sService, err := %s.NewService(ctx, option.WithAPIKey("AIza..."))`, pkg, pkg)
pn("//")
pn("// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:")
pn("//")
pn("// config := &oauth2.Config{...}")
pn("// // ...")
pn("// token, err := config.Exchange(ctx, ...)")
pn("// %sService, err := %s.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))", pkg, pkg)
pn("//")
pn("// See https://godoc.org/google.golang.org/api/option/ for details on options.")
a.printPkgDocs()
pn("package %s // import %q", pkg, a.Target())
p("\n")
pn("import (")
Expand Down
25 changes: 19 additions & 6 deletions google-api-go-generator/testdata/any.want
View file
Expand Up @@ -8,6 +8,17 @@
//
// This package is DEPRECATED. Use package cloud.google.com/go/logging instead.
//
// # Library status
//
// These client libraries are officially supported by Google. However, this
// library is considered complete and is in maintenance mode. This means
// that we will address critical bugs and security issues but will not add
// any new features.
//
// When possible, we recommend using our newer
// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
// that are still actively being worked and iterated on.
//
// # Creating a client
//
// Usage example:
Expand All @@ -17,24 +28,26 @@
// ctx := context.Background()
// loggingService, err := logging.NewService(ctx)
//
// In this example, Google Application Default Credentials are used for authentication.
//
// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
// In this example, Google Application Default Credentials are used for
// authentication. For information on how to create and obtain Application
// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
//
// # Other authentication options
//
// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
// To use an API key for authentication (note: some APIs do not support API
// keys), use [google.golang.org/api/option.WithAPIKey]:
//
// loggingService, err := logging.NewService(ctx, option.WithAPIKey("AIza..."))
//
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
// flow, use [google.golang.org/api/option.WithTokenSource]:
//
// config := &oauth2.Config{...}
// // ...
// token, err := config.Exchange(ctx, ...)
// loggingService, err := logging.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
//
// See https://godoc.org/google.golang.org/api/option/ for details on options.
// See [google.golang.org/api/option.ClientOption] for details on options.
package logging // import "google.golang.org/api/logging/v1beta3"

import (
Expand Down
25 changes: 19 additions & 6 deletions google-api-go-generator/testdata/arrayofarray-1.want
View file
Expand Up @@ -6,6 +6,17 @@

// Package arrayofarray provides access to the Example API.
//
// # Library status
//
// These client libraries are officially supported by Google. However, this
// library is considered complete and is in maintenance mode. This means
// that we will address critical bugs and security issues but will not add
// any new features.
//
// When possible, we recommend using our newer
// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
// that are still actively being worked and iterated on.
//
// # Creating a client
//
// Usage example:
Expand All @@ -15,24 +26,26 @@
// ctx := context.Background()
// arrayofarrayService, err := arrayofarray.NewService(ctx)
//
// In this example, Google Application Default Credentials are used for authentication.
//
// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
// In this example, Google Application Default Credentials are used for
// authentication. For information on how to create and obtain Application
// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
//
// # Other authentication options
//
// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
// To use an API key for authentication (note: some APIs do not support API
// keys), use [google.golang.org/api/option.WithAPIKey]:
//
// arrayofarrayService, err := arrayofarray.NewService(ctx, option.WithAPIKey("AIza..."))
//
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
// flow, use [google.golang.org/api/option.WithTokenSource]:
//
// config := &oauth2.Config{...}
// // ...
// token, err := config.Exchange(ctx, ...)
// arrayofarrayService, err := arrayofarray.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
//
// See https://godoc.org/google.golang.org/api/option/ for details on options.
// See [google.golang.org/api/option.ClientOption] for details on options.
package arrayofarray // import "google.golang.org/api/arrayofarray/v1"

import (
Expand Down
25 changes: 19 additions & 6 deletions google-api-go-generator/testdata/arrayofenum.want
View file
Expand Up @@ -6,6 +6,17 @@

// Package arrayofenum provides access to the Example API.
//
// # Library status
//
// These client libraries are officially supported by Google. However, this
// library is considered complete and is in maintenance mode. This means
// that we will address critical bugs and security issues but will not add
// any new features.
//
// When possible, we recommend using our newer
// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
// that are still actively being worked and iterated on.
//
// # Creating a client
//
// Usage example:
Expand All @@ -15,24 +26,26 @@
// ctx := context.Background()
// arrayofenumService, err := arrayofenum.NewService(ctx)
//
// In this example, Google Application Default Credentials are used for authentication.
//
// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
// In this example, Google Application Default Credentials are used for
// authentication. For information on how to create and obtain Application
// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
//
// # Other authentication options
//
// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
// To use an API key for authentication (note: some APIs do not support API
// keys), use [google.golang.org/api/option.WithAPIKey]:
//
// arrayofenumService, err := arrayofenum.NewService(ctx, option.WithAPIKey("AIza..."))
//
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
// flow, use [google.golang.org/api/option.WithTokenSource]:
//
// config := &oauth2.Config{...}
// // ...
// token, err := config.Exchange(ctx, ...)
// arrayofenumService, err := arrayofenum.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
//
// See https://godoc.org/google.golang.org/api/option/ for details on options.
// See [google.golang.org/api/option.ClientOption] for details on options.
package arrayofenum // import "google.golang.org/api/arrayofenum/v1"

import (
Expand Down
25 changes: 19 additions & 6 deletions google-api-go-generator/testdata/arrayofmapofobjects.want
View file
Expand Up @@ -6,6 +6,17 @@

// Package arrayofmapofstrings provides access to the Example API.
//
// # Library status
//
// These client libraries are officially supported by Google. However, this
// library is considered complete and is in maintenance mode. This means
// that we will address critical bugs and security issues but will not add
// any new features.
//
// When possible, we recommend using our newer
// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
// that are still actively being worked and iterated on.
//
// # Creating a client
//
// Usage example:
Expand All @@ -15,24 +26,26 @@
// ctx := context.Background()
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx)
//
// In this example, Google Application Default Credentials are used for authentication.
//
// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
// In this example, Google Application Default Credentials are used for
// authentication. For information on how to create and obtain Application
// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
//
// # Other authentication options
//
// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
// To use an API key for authentication (note: some APIs do not support API
// keys), use [google.golang.org/api/option.WithAPIKey]:
//
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx, option.WithAPIKey("AIza..."))
//
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
// flow, use [google.golang.org/api/option.WithTokenSource]:
//
// config := &oauth2.Config{...}
// // ...
// token, err := config.Exchange(ctx, ...)
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
//
// See https://godoc.org/google.golang.org/api/option/ for details on options.
// See [google.golang.org/api/option.ClientOption] for details on options.
package arrayofmapofstrings // import "google.golang.org/api/arrayofmapofstrings/v1"

import (
Expand Down
25 changes: 19 additions & 6 deletions google-api-go-generator/testdata/arrayofmapofstrings.want
View file
Expand Up @@ -6,6 +6,17 @@

// Package arrayofmapofstrings provides access to the Example API.
//
// # Library status
//
// These client libraries are officially supported by Google. However, this
// library is considered complete and is in maintenance mode. This means
// that we will address critical bugs and security issues but will not add
// any new features.
//
// When possible, we recommend using our newer
// [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
// that are still actively being worked and iterated on.
//
// # Creating a client
//
// Usage example:
Expand All @@ -15,24 +26,26 @@
// ctx := context.Background()
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx)
//
// In this example, Google Application Default Credentials are used for authentication.
//
// For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
// In this example, Google Application Default Credentials are used for
// authentication. For information on how to create and obtain Application
// Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
//
// # Other authentication options
//
// To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
// To use an API key for authentication (note: some APIs do not support API
// keys), use [google.golang.org/api/option.WithAPIKey]:
//
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx, option.WithAPIKey("AIza..."))
//
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
// To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
// flow, use [google.golang.org/api/option.WithTokenSource]:
//
// config := &oauth2.Config{...}
// // ...
// token, err := config.Exchange(ctx, ...)
// arrayofmapofstringsService, err := arrayofmapofstrings.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
//
// See https://godoc.org/google.golang.org/api/option/ for details on options.
// See [google.golang.org/api/option.ClientOption] for details on options.
package arrayofmapofstrings // import "google.golang.org/api/arrayofmapofstrings/v1"

import (
Expand Down

0 comments on commit 62d88ff

Please sign in to comment.