Repository: googleapis/gapic-generator-go
Pull request #1575 (2024-10-24 15:30:41)

chore: simplify package docs and add import statement
- Added a comment on how to download the library
- Removed redundant code in package docs

Internal bug: 372979301


Patch:
diff --git a/internal/gengapic/doc_file.go b/internal/gengapic/doc_file.go
index af7a6d1..0801e10 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 8441b20..213bb61 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("")


Test patch:
diff --git a/internal/gengapic/testdata/doc_file.want b/internal/gengapic/testdata/doc_file.want
index d32c5c2..97fb473 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 084202c..299de1d 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 6e8d009..b8dcc67 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 051cbac..018e88b 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 b294bda..6ea0ad6 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 367cc2d..4ab0138 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 587108b..9a68f0a 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: