From f0724e93a4b13f944f4acfef03ad3670609ac8ca Mon Sep 17 00:00:00 2001 From: Cody Oss Date: Thu, 24 Oct 2024 10:29:18 -0500 Subject: [PATCH] chore: simplify package docs and add import statement Internal bug: 372979301 --- internal/gengapic/doc_file.go | 6 +++--- internal/gengapic/example.go | 16 ++++++++++++++-- internal/gengapic/testdata/doc_file.want | 14 ++------------ internal/gengapic/testdata/doc_file_alpha.want | 14 ++------------ .../testdata/doc_file_alpha_emptyservice.want | 1 + internal/gengapic/testdata/doc_file_beta.want | 14 ++------------ .../testdata/doc_file_beta_emptyservice.want | 1 + .../doc_file_deprecated_emptyservice.want | 1 + .../gengapic/testdata/doc_file_emptyservice.want | 1 + 9 files changed, 27 insertions(+), 41 deletions(-) diff --git a/internal/gengapic/doc_file.go b/internal/gengapic/doc_file.go index af7a6d182..0801e10c5 100644 --- a/internal/gengapic/doc_file.go +++ b/internal/gengapic/doc_file.go @@ -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) @@ -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) diff --git a/internal/gengapic/example.go b/internal/gengapic/example.go index 8441b2091..213bb6184 100644 --- a/internal/gengapic/example.go +++ b/internal/gengapic/example.go @@ -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:") @@ -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 @@ -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("") diff --git a/internal/gengapic/testdata/doc_file.want b/internal/gengapic/testdata/doc_file.want index d32c5c289..97fb47311 100644 --- a/internal/gengapic/testdata/doc_file.want +++ b/internal/gengapic/testdata/doc_file.want @@ -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: @@ -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. diff --git a/internal/gengapic/testdata/doc_file_alpha.want b/internal/gengapic/testdata/doc_file_alpha.want index 084202c99..299de1d5a 100644 --- a/internal/gengapic/testdata/doc_file_alpha.want +++ b/internal/gengapic/testdata/doc_file_alpha.want @@ -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: @@ -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. diff --git a/internal/gengapic/testdata/doc_file_alpha_emptyservice.want b/internal/gengapic/testdata/doc_file_alpha_emptyservice.want index 6e8d0094b..b8dcc676f 100644 --- a/internal/gengapic/testdata/doc_file_alpha_emptyservice.want +++ b/internal/gengapic/testdata/doc_file_alpha_emptyservice.want @@ -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: diff --git a/internal/gengapic/testdata/doc_file_beta.want b/internal/gengapic/testdata/doc_file_beta.want index 051cbac3b..018e88bec 100644 --- a/internal/gengapic/testdata/doc_file_beta.want +++ b/internal/gengapic/testdata/doc_file_beta.want @@ -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: @@ -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. diff --git a/internal/gengapic/testdata/doc_file_beta_emptyservice.want b/internal/gengapic/testdata/doc_file_beta_emptyservice.want index b294bdacb..6ea0ad6a8 100644 --- a/internal/gengapic/testdata/doc_file_beta_emptyservice.want +++ b/internal/gengapic/testdata/doc_file_beta_emptyservice.want @@ -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: diff --git a/internal/gengapic/testdata/doc_file_deprecated_emptyservice.want b/internal/gengapic/testdata/doc_file_deprecated_emptyservice.want index 367cc2df8..4ab01384e 100644 --- a/internal/gengapic/testdata/doc_file_deprecated_emptyservice.want +++ b/internal/gengapic/testdata/doc_file_deprecated_emptyservice.want @@ -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: diff --git a/internal/gengapic/testdata/doc_file_emptyservice.want b/internal/gengapic/testdata/doc_file_emptyservice.want index 587108b69..9a68f0aa9 100644 --- a/internal/gengapic/testdata/doc_file_emptyservice.want +++ b/internal/gengapic/testdata/doc_file_emptyservice.want @@ -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: