fix(gengapic): support deprecated as a release-level option value (#1390

)

internal/gengapic/doc_file.go

@@ -62,6 +62,9 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptor.Servi
 	case beta:
 		p("//")
 		p("//   NOTE: This package is in beta. It is not stable, and may be subject to changes.")
+	case deprecated:
+		p("//")
+		p("// Deprecated: Find the newer version of this package in the module.")
 	}
 
 	p("//")

internal/gengapic/doc_file_test.go

@@ -141,6 +141,10 @@ func TestDocFileEmptyService(t *testing.T) {
 			relLvl: beta,
 			want:   filepath.Join("testdata", "doc_file_beta_emptyservice.want"),
 		},
+		{
+			relLvl: deprecated,
+			want:   filepath.Join("testdata", "doc_file_deprecated_emptyservice.want"),
+		},
 	} {
 		g.opts.relLvl = tst.relLvl
 		g.genDocFile(43, []string{"https://foo.bar.com/auth", "https://zip.zap.com/auth"}, serv)

internal/gengapic/gengapic.go

@@ -40,6 +40,7 @@ const (
 	httpBodyType            = ".google.api.HttpBody"
 	alpha                   = "alpha"
 	beta                    = "beta"
+	deprecated              = "deprecated"
 	disableDeadlinesVar     = "GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE"
 	fieldTypeBool           = descriptor.FieldDescriptorProto_TYPE_BOOL
 	fieldTypeString         = descriptor.FieldDescriptorProto_TYPE_STRING

internal/gengapic/options.go

@@ -57,7 +57,7 @@ type options struct {
 // * grpc-service-config (filepath)
 // * module (name)
 // * Mfile=import (e.g. Mgoogle/storage/v2/storage.proto=cloud.google.com/go/storage/internal/apiv2/stubs)
-// * release-level (one of 'alpha', 'beta', or empty)
+// * release-level (one of 'alpha', 'beta', 'deprecated', or empty)
 // * transport ('+' separated list of transport backends to generate)
 // * metadata (enable GAPIC metadata generation)
 // * omit-snippets (skip example code snippets generation to the `internal/generated/snippets` path)

internal/gengapic/testdata/doc_file_deprecated_emptyservice.want

@@ -0,0 +1,98 @@
+// Copyright 43 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Code generated by protoc-gen-go_gapic. DO NOT EDIT.
+
+// Package awesome is an auto-generated package for the
+// Awesome Bar API.
+//
+// The Awesome Bar API is really really awesome. It enables the use of Foo
+// (at https://api.foo.com) with Buz (at https://api.buz.com) and Baz (at
+// https://api.baz.com) to acclerate bar.
+//
+// Deprecated: Find the newer version of this package in the module.
+//
+// General documentation
+//
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
+//
+// Example usage
+//
+// 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.
+//  }
+//  defer c.Close()
+//
+// The client will use your default application credentials. Clients should be reused instead of created as needed.
+// The methods of Client are safe for concurrent use by multiple goroutines.
+// The returned client must be Closed when it is done being used.
+//
+// Use of Context
+//
+// The ctx passed to NewFooClient is used for authentication requests and
+// for creating the underlying connection, but is not used for subsequent calls.
+// Individual methods on the client use the ctx given to them.
+//
+// To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
+package awesome // import "path/to/awesome"
+
+import (
+	"context"
+
+	"google.golang.org/api/option"
+)
+
+// For more information on implementing a client constructor hook, see
+// https://github.com/googleapis/google-cloud-go/wiki/Customizing-constructors.
+type clientHookParams struct{}
+type clientHook func(context.Context, clientHookParams) ([]option.ClientOption, error)
+
+var versionClient string
+
+func getVersionClient() string {
+	if versionClient == "" {
+		return "UNKNOWN"
+	}
+	return versionClient
+}
+
+// DefaultAuthScopes reports the default set of authentication scopes to use with this package.
+func DefaultAuthScopes() []string {
+	return []string{
+		"https://foo.bar.com/auth",
+		"https://zip.zap.com/auth",
+	}
+}