Skip to content

Commit

Permalink
chore: simplify package docs and add import statement (#1575)
Browse files Browse the repository at this point in the history
- Added a comment on how to download the library
- Removed redundant code in package docs

Internal bug: 372979301
  • Loading branch information
codyoss authored Oct 24, 2024
1 parent 52d6acd commit 7e64160
Show file tree
Hide file tree
Showing 9 changed files with 27 additions and 41 deletions.
6 changes: 3 additions & 3 deletions internal/gengapic/doc_file.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptorpb.Ser
servName := pbinfo.ReduceServName(serv.GetName(), g.opts.pkgName)
tmpClient := g.pt
g.pt = printer.P{}
g.exampleInitClient(g.opts.pkgName, servName)
g.exampleInitClientWithOpts(g.opts.pkgName, servName, true)
snipClient := g.pt.String()
g.pt = tmpClient
g.codesnippet(snipClient)
Expand All @@ -99,12 +99,12 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptorpb.Ser
if len(serv.GetMethod()) > 0 {
p("// Using the Client")
p("//")
p("// The following is an example of making an API call with the newly created client.")
p("// The following is an example of making an API call with the newly created client, mentioned above.")
p("//")
// Code block for client using the first method of the service
tmpMethod := g.pt
g.pt = printer.P{}
g.exampleMethodBody(g.opts.pkgName, servName, serv.GetMethod()[0])
g.exampleMethodBodyWithOpts(g.opts.pkgName, servName, serv.GetMethod()[0], true)
snipMethod := g.pt.String()
g.pt = tmpMethod
g.codesnippet(snipMethod)
Expand Down
16 changes: 14 additions & 2 deletions internal/gengapic/example.go
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,14 @@ func (g *generator) exampleClientFactory(pkgName, servName string) {
}

func (g *generator) exampleInitClient(pkgName, servName string) {
p := g.printf
g.exampleInitClientWithOpts(pkgName, servName, false)
}

func (g *generator) exampleInitClientWithOpts(pkgName, servName string, isPackageDoc bool) {
p := g.printf
if isPackageDoc {
p("// go get %s@latest", g.opts.pkgPath)
}
p("ctx := context.Background()")
p("// This snippet has been automatically generated and should be regarded as a code template only.")
p("// It will require modifications to work:")
Expand Down Expand Up @@ -153,6 +159,10 @@ func (g *generator) exampleMethod(pkgName, servName string, m *descriptorpb.Meth
}

func (g *generator) exampleMethodBody(pkgName, servName string, m *descriptorpb.MethodDescriptorProto) error {
return g.exampleMethodBodyWithOpts(pkgName, servName, m, false)
}

func (g *generator) exampleMethodBodyWithOpts(pkgName, servName string, m *descriptorpb.MethodDescriptorProto, isPackageDoc bool) error {
if m.GetClientStreaming() != m.GetServerStreaming() {
// TODO(pongad): implement this correctly.
return nil
Expand Down Expand Up @@ -188,7 +198,9 @@ func (g *generator) exampleMethodBody(pkgName, servName string, m *descriptorpb.
if t == rest {
s += "REST"
}
g.exampleInitClient(pkgName, s)
if !isPackageDoc {
g.exampleInitClient(pkgName, s)
}

if !m.GetClientStreaming() && !m.GetServerStreaming() {
p("")
Expand Down
14 changes: 2 additions & 12 deletions internal/gengapic/testdata/doc_file.want
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand All @@ -53,19 +54,8 @@
//
// Using the Client
//
// The following is an example of making an API call with the newly created client.
// The following is an example of making an API call with the newly created client, mentioned above.
//
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
// // - It may require correct/in-range values for request initialization.
// // - It may require specifying regional endpoints when creating the service client as shown in:
// // https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
// c, err := secretmanager.NewClient(ctx)
// if err != nil {
// // TODO: Handle error.
// }
// defer c.Close()
//
// req := &secretmanagerpb.CreateSecretRequest{
// // TODO: Fill request struct fields.
Expand Down
14 changes: 2 additions & 12 deletions internal/gengapic/testdata/doc_file_alpha.want
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand All @@ -55,19 +56,8 @@
//
// Using the Client
//
// The following is an example of making an API call with the newly created client.
// The following is an example of making an API call with the newly created client, mentioned above.
//
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
// // - It may require correct/in-range values for request initialization.
// // - It may require specifying regional endpoints when creating the service client as shown in:
// // https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
// c, err := secretmanager.NewClient(ctx)
// if err != nil {
// // TODO: Handle error.
// }
// defer c.Close()
//
// req := &secretmanagerpb.CreateSecretRequest{
// // TODO: Fill request struct fields.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand Down
14 changes: 2 additions & 12 deletions internal/gengapic/testdata/doc_file_beta.want
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand All @@ -55,19 +56,8 @@
//
// Using the Client
//
// The following is an example of making an API call with the newly created client.
// The following is an example of making an API call with the newly created client, mentioned above.
//
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
// // - It may require correct/in-range values for request initialization.
// // - It may require specifying regional endpoints when creating the service client as shown in:
// // https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
// c, err := secretmanager.NewClient(ctx)
// if err != nil {
// // TODO: Handle error.
// }
// defer c.Close()
//
// req := &secretmanagerpb.CreateSecretRequest{
// // TODO: Fill request struct fields.
Expand Down
1 change: 1 addition & 0 deletions internal/gengapic/testdata/doc_file_beta_emptyservice.want
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand Down
1 change: 1 addition & 0 deletions internal/gengapic/testdata/doc_file_emptyservice.want
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
// Example usage
//
// To get started with this package, create a client.
// // go get cloud.google.com/go/secretmanager/apiv1@latest
// ctx := context.Background()
// // This snippet has been automatically generated and should be regarded as a code template only.
// // It will require modifications to work:
Expand Down

0 comments on commit 7e64160

Please sign in to comment.