feat(gengapic): add in-line snippet comment to example.go (#1120)

internal/gengapic/example.go

@@ -64,6 +64,11 @@ func (g *generator) exampleInitClient(pkgName, servName string) {
 	p := g.printf
 
 	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:")
+	p("// - It may require correct/in-range values for request initialization.")
+	p("// - It may require specifying regional endpoints when creating the service client as shown in:")
+	p("//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options")
 	p("c, err := %s.New%sClient(ctx)", pkgName, servName)
 	p("if err != nil {")
 	p("  // TODO: Handle error.")

internal/gengapic/testdata/custom_op_example.want

@@ -1,5 +1,10 @@
 func ExampleNewFooRESTClient() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -12,6 +17,11 @@ func ExampleNewFooRESTClient() {
 
 func ExampleFooClient_GetEmptyThing() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -30,6 +40,11 @@ func ExampleFooClient_GetEmptyThing() {
 
 func ExampleFooClient_GetOneThing() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -50,6 +65,11 @@ func ExampleFooClient_GetOneThing() {
 
 func ExampleFooClient_GetBigThing() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -75,6 +95,11 @@ func ExampleFooClient_GetBigThing() {
 
 func ExampleFooClient_GetManyThings() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -101,6 +126,11 @@ func ExampleFooClient_GetManyThings() {
 
 func ExampleFooClient_BidiThings() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -136,6 +166,11 @@ func ExampleFooClient_BidiThings() {
 
 func ExampleFooClient_EmptyLRO() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -159,6 +194,11 @@ func ExampleFooClient_EmptyLRO() {
 
 func ExampleFooClient_RespLRO() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.
@@ -184,6 +224,11 @@ func ExampleFooClient_RespLRO() {
 
 func ExampleFooClient_CustomOp() {
 	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 := Bar.NewFooRESTClient(ctx)
 	if err != nil {
 		// TODO: Handle error.

internal/gengapic/testdata/doc_file.want

@@ -25,6 +25,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.
@@ -40,6 +45,11 @@
 // The following is an example of making an API call with the newly created client.
 //
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.

internal/gengapic/testdata/doc_file_alpha.want

@@ -27,6 +27,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.
@@ -42,6 +47,11 @@
 // The following is an example of making an API call with the newly created client.
 //
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.

internal/gengapic/testdata/doc_file_alpha_emptyservice.want

@@ -27,6 +27,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.

internal/gengapic/testdata/doc_file_beta.want

@@ -27,6 +27,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.
@@ -42,6 +47,11 @@
 // The following is an example of making an API call with the newly created client.
 //
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.

internal/gengapic/testdata/doc_file_beta_emptyservice.want

@@ -27,6 +27,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.

internal/gengapic/testdata/doc_file_emptyservice.want

@@ -25,6 +25,11 @@
 //
 // To get started with this package, create a client.
 //  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 := awesome.NewFooClient(ctx)
 //  if err != nil {
 //  	// TODO: Handle error.