gapic-generator 0.2.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d4dfb48094e9e52bcc6563460bfc9bf458496d81607777cecd231f497025e1a
-  data.tar.gz: a52c7434b5497d85543ac55149d54987ebfa950c191b1af7673a1f32fa58dd39
+  metadata.gz: 141fbba25c93dca9ccac5c4a380f7a0f8c1c1643ef2e9517fbb158ba92db822c
+  data.tar.gz: c61466f199a4d34b6c1fefea9aa8773abc7d9514dfb232385a1e6806e49140f2
 SHA512:
-  metadata.gz: be4a0672c23603bc0df2174f52d5cdc5ddd60264f322079f9c96e03bafcfa2b7fed187103ad864b19cc1a7e1ee3bb50eecc0e64a29e2534d4183c574fa5d1cc7
-  data.tar.gz: a80ec4c7604511c4b7d87fb4868dd928676aaaec205a32fc7cbda8facd52e7f9a347d1104ba8840df80f2e3df81f87b831483615540761ffdffd45575a129aa4
+  metadata.gz: 1cefa5cb936a4d9f211c0af9f03a9bcbd4ba76f35417cc3a1723164c949dc93b0f9f8be3602ac882d19c2a1109eed7b47150f4be4587ab5d5a368d7942df14f5
+  data.tar.gz: eab763dd18a81db68af29cc55e54b69f7f8fe504bca56aa93925a66e0c8f548335a4700c0cb89cb13aef65f5de7d640dc8dc0a704190e6a06f7ecdaeb294b065

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Release History for gapic-generator
 
+### 0.3.3 / 2020-04-13
+
+* Fix cross-reference links to multi-word enum values.
+
+### 0.3.2 / 2020-04-12
+
+* Fix the talent.v4beta1 hack.
+
+### 0.3.1 / 2020-04-11
+
+* Disable ModuleLength metric for generated code.
+* Omit nonconforming resource patterns instead of crashing.
+
+### 0.3.0 / 2020-04-10
+
+* Detect when a resource is referenced implicitly via child_type, and generate path helpers.
+* Update grpc-google-iam-v1 dependency to require the latest version.
+* Generated require graph is more sane and does not include cycles.
+* The bundler entrypoint now loads the entire gem for wrapper gems.
+* Generated readmes are more useful and include a quickstart.
+* Package and service modules now have basic documentation.
+* Overloads for methods now have basic explanatory documentation, including how to pass an empty request.
+* Request object documentation no longer duplicates the method documentation.
+
+### 0.2.3 / 2020-04-06
+
+* No changes
+
+### 0.2.2 / 2020-03-31
+
+* Updates to common protos, especially core types which were more than a year old.
+
+### 0.2.1 / 2020-03-26
+
+* Fix service address for LRO operation clients.
+* Tweak sample task names for wrapper-gem Rakefiles.
+
 ### 0.2.0 / 2020-03-23
 
 Generation updates:

data/lib/gapic/formatting_utils.rb

@@ -140,8 +140,10 @@ module Gapic
           "{#{convert_address_to_ruby entity}::Client #{text}}"
         when Gapic::Schema::Method
           "{#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
-        when Gapic::Schema::Message, Gapic::Schema::Enum, Gapic::Schema::EnumValue
+        when Gapic::Schema::Message, Gapic::Schema::Enum
           "{#{convert_address_to_ruby entity} #{text}}"
+        when Gapic::Schema::EnumValue
+          "{#{convert_address_to_ruby entity.parent}::#{entity.name} #{text}}"
         when Gapic::Schema::Field
           "{#{convert_address_to_ruby entity.parent}##{entity.name} #{text}}"
         end

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.2.0"
+    VERSION = "0.3.3"
   end
 end

data/lib/gapic/generators/default_generator.rb

@@ -63,16 +63,17 @@ module Gapic
         end
 
         # Gem level files
-        files << g("gem/gitignore.erb", ".gitignore",                   gem: gem)
-        files << g("gem/version.erb",   "lib/#{gem.version_file_path}", gem: gem)
-        files << g("gem/gemspec.erb",   "#{gem.name}.gemspec",          gem: gem)
-        files << g("gem/gemfile.erb",   "Gemfile",                      gem: gem)
-        files << g("gem/rakefile.erb",  "Rakefile",                     gem: gem)
-        files << g("gem/readme.erb",    "README.md",                    gem: gem)
-        files << g("gem/changelog.erb", "CHANGELOG.md",                 gem: gem)
-        files << g("gem/rubocop.erb",   ".rubocop.yml",                 gem: gem)
-        files << g("gem/yardopts.erb",  ".yardopts",                    gem: gem)
-        files << g("gem/license.erb",   "LICENSE.md",                   gem: gem)
+        files << g("gem/gitignore.erb",  ".gitignore",                   gem: gem)
+        files << g("gem/version.erb",    "lib/#{gem.version_file_path}", gem: gem)
+        files << g("gem/gemspec.erb",    "#{gem.name}.gemspec",          gem: gem)
+        files << g("gem/gemfile.erb",    "Gemfile",                      gem: gem)
+        files << g("gem/rakefile.erb",   "Rakefile",                     gem: gem)
+        files << g("gem/readme.erb",     "README.md",                    gem: gem)
+        files << g("gem/changelog.erb",  "CHANGELOG.md",                 gem: gem)
+        files << g("gem/rubocop.erb",    ".rubocop.yml",                 gem: gem)
+        files << g("gem/yardopts.erb",   ".yardopts",                    gem: gem)
+        files << g("gem/license.erb",    "LICENSE.md",                   gem: gem)
+        files << g("gem/entrypoint.erb", "lib/#{gem.name}.rb",           gem: gem)
 
         gem.proto_files.each do |proto_file|
           files << g("proto_docs/proto_file.erb", "proto_docs/#{proto_file.docs_file_path}", file: proto_file)

data/lib/gapic/presenters/field_presenter.rb

@@ -95,7 +95,7 @@ module Gapic
         base_type =
           if field.message?
             type = message_ruby_type field.message
-            output ? type : "#{type} | Hash"
+            output ? type : "#{type}, Hash"
           elsif field.enum?
             # TODO: handle when arg message is nil and enum is the type
             message_ruby_type field.enum

data/lib/gapic/presenters/gem_presenter.rb

@@ -37,6 +37,10 @@ module Gapic
         end
       end
 
+      def packages?
+        !packages.empty?
+      end
+
       def services
         @services ||= begin
           files = @api.generate_files
@@ -134,11 +138,13 @@ module Gapic
       end
 
       def free_tier?
-        gem_config(:free_tier) ? true : false
+        # Default to false unless the config is explicitly set to "true"
+        gem_config(:free_tier) == "true"
       end
 
       def yard_strict?
-        gem_config(:yard_strict) ? true : false
+        # Default to true unless the config is explicitly set to "false"
+        gem_config(:yard_strict) != "false"
       end
 
       def entrypoint_require

data/lib/gapic/presenters/method_presenter.rb

@@ -160,6 +160,16 @@ module Gapic
 
       def paged?
         return false if server_streaming? # Cannot page a streaming response
+
+        # HACK(dazuma, 2020-04-06): Two specific RPCs should not be paged.
+        # This is an intentionally hard-coded exception (and a temporary one,
+        # to be removed when these methods no longer conform to AIP-4233.) For
+        # detailed information, see internal link go/actools-talent-pagination.
+        address = @method.address.join "."
+        return false if address == "google.cloud.talent.v4beta1.ProfileService.SearchProfiles"
+        return false if address == "google.cloud.talent.v4beta1.JobService.SearchJobs"
+        return false if address == "google.cloud.talent.v4beta1.JobService.SearchJobsForAlert"
+
         paged_request?(@method.input) && paged_response?(@method.output)
       end
 
@@ -205,7 +215,7 @@ module Gapic
 
       def doc_types_for arg
         if arg.message?
-          "#{message_ruby_type arg.message} | Hash"
+          "#{message_ruby_type arg.message}, Hash"
         elsif arg.enum?
           # TODO: handle when arg message is nil and enum is the type
           message_ruby_type arg.enum

data/lib/gapic/presenters/package_presenter.rb

@@ -45,6 +45,14 @@ module Gapic
         ruby_namespace_for_address address
       end
 
+      def parent_namespace
+        namespace.split("::")[0...-1].join("::")
+      end
+
+      def module_name
+        namespace.split("::").last
+      end
+
       def services
         @services ||= begin
           files = @api.generate_files.select { |f| f.package == @package }

data/lib/gapic/presenters/resource_presenter.rb

@@ -38,15 +38,9 @@ module Gapic
           )
         end
 
-        @patterns.each do |pattern|
-          # URI path template verification for expected proto resource usage
-          if named_arg_patterns? pattern.segments
-            raise ArgumentError, "only resources without named patterns are supported, " \
-                                " not #{pattern.template}"
-          elsif positional_args? pattern.segments
-            raise ArgumentError, "only resources with named segments are supported, " \
-                                " not #{pattern.template}"
-          end
+        # Keep only patterns that can be used to create path helpers
+        @patterns.reject! do |pattern|
+          named_arg_patterns?(pattern.segments) || positional_args?(pattern.segments)
         end
       end
 

data/lib/gapic/presenters/service_presenter.rb

@@ -27,9 +27,10 @@ module Gapic
       include Gapic::Helpers::FilepathHelper
       include Gapic::Helpers::NamespaceHelper
 
-      def initialize api, service
+      def initialize api, service, parent_service: nil
         @api = api
         @service = service
+        @parent_service = parent_service
       end
 
       def gem
@@ -77,6 +78,10 @@ module Gapic
         fix_namespace @api, "#{namespace}::#{name}"
       end
 
+      def module_name
+        proto_service_name_full.split("::").last
+      end
+
       def proto_service_file_path
         @service.parent.name.sub ".proto", "_pb.rb"
       end
@@ -113,6 +118,10 @@ module Gapic
         service_file_path.split("/").last
       end
 
+      def service_directory_name
+        service_require.split("/").last
+      end
+
       def service_require
         ruby_file_path @api, proto_service_name_full
       end
@@ -146,6 +155,7 @@ module Gapic
       end
 
       def client_endpoint
+        return @parent_service.client_endpoint if @parent_service
         @service.host || default_config(:default_host) || "localhost"
       end
 
@@ -267,8 +277,7 @@ module Gapic
 
       def lro_service
         lro = @service.parent.parent.files.find { |file| file.name == "google/longrunning/operations.proto" }
-
-        return ServicePresenter.new @api, lro.services.first unless lro.nil?
+        return ServicePresenter.new @api, lro.services.first, parent_service: self unless lro.nil?
       end
 
       def config_channel_args

data/lib/gapic/resource_lookup.rb

@@ -26,64 +26,42 @@ module Gapic
 
     # @private
     def lookup!
-      resources = @api.files.flat_map { |file| lookup_file_resource_descriptors file }
-      resources.compact.uniq
-    end
-
-    # @private
-    def lookup_file_resource_descriptors file
       resources = []
-      resources += file.resources.select { |resource| service_resource_types.include? resource.type }
-      resources += file.messages.flat_map { |message| lookup_message_resources_descriptors message }
-      resources
-    end
-
-    # @private
-    def service_resource_types
-      @service_resource_types ||= begin
-        @service.methods.flat_map do |method|
-          input_resource_types = message_resource_types method.input
-
-          if @api.generate_path_helpers_output?
-            output_resource_types = message_resource_types method.output
-            input_resource_types + output_resource_types
-          else
-            input_resource_types
-          end
-        end.uniq
+      @service.methods.each do |method|
+        resources.concat resources_for_message(method.input)
+        resources.concat resources_for_message(method.output) if @api.generate_path_helpers_output?
       end
+      resources.uniq
     end
 
     # @private
-    def message_resource_types message, seen_messages = []
-      return [] if seen_messages.include? message
+    def resources_for_message message, seen_messages = []
+      resources = []
+      return resources if seen_messages.include? message
       seen_messages << message
-      resource_types = []
-      resource_types << message.resource.type if message.resource
-      resource_types += message.nested_messages.map do |nested_message|
-        message_resource_types nested_message, seen_messages
+      resources << message.resource if message.resource
+      message.nested_messages.each do |nested_message|
+        resources.concat resources_for_message(nested_message, seen_messages)
       end
       message.fields.each do |field|
-        resource_types << field.resource_reference.type if field.resource_reference
-        resource_types += message_resource_types field.message, seen_messages if field.message?
+        resources.concat resources_for_reference(field.resource_reference) if field.resource_reference
+        resources.concat resources_for_message(field.message, seen_messages) if field.message?
       end
-      resource_types.flatten
+      resources
     end
 
     # @private
-    def lookup_message_resources_descriptors message
-      resources = []
-
-      # We don't expect service_resource_types to iclude nil, so we can use message.resource&.type
-      resources << message.resource if service_resource_types.include? message.resource&.type
-
-      if message.nested_messages
-        resources += message.nested_messages.flat_map do |nested_message|
-          lookup_message_resources_descriptors nested_message
-        end
+    # Given a reference (either a type or child type), return the corresponding
+    # resources.
+    def resources_for_reference reference
+      if (type = reference.type) && !type.empty?
+        Array(@api.lookup_resource_type(type))
+      elsif (child_type = reference.child_type) && !child_type.empty?
+        child_resource = @api.lookup_resource_type child_type
+        child_resource ? child_resource.parent_resources : []
+      else
+        []
       end
-
-      resources
     end
 
     # Lookup all resources for a given service.

data/lib/gapic/schema/api.rb

@@ -51,6 +51,7 @@ module Gapic
           loader.load_file fd, request.file_to_generate.include?(fd.name)
         end
         @files.each { |f| f.parent = self }
+        @resource_types = analyze_resources
       end
 
       def containing_api
@@ -243,8 +244,53 @@ module Gapic
         end
       end
 
+      # Get a resource given its type string
+      def lookup_resource_type resource_type
+        @resource_types[resource_type]
+      end
+
       private
 
+      # Does a pre-analysis of all resources defined in the job. This has
+      # two effects:
+      # * Side effect: each resource has its parent_resources field set.
+      # * A mapping from resource type to resource wrapper is returned.
+      def analyze_resources
+        # In order to set parent_resources, we first populate a mapping from
+        # parsed pattern to resource mapping (in the patterns variable). This
+        # is done in one pass along with populating the resource type mapping.
+        # Then, we go through all resources again, get its expected parent
+        # patterns, and anything that shows up in the patterns mapping is taken
+        # to be a parent.
+        types = {}
+        patterns = {}
+        @files.each do |file|
+          file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
+          file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
+        end
+        types.each do |_type, resource|
+          parents = resource.parsed_parent_patterns
+                            .map { |pat| patterns[pat] }
+                            .compact.uniq
+          resource.parent_resources.replace parents
+        end
+        types
+      end
+
+      def populate_resource_lookups resource, types, patterns
+        types[resource.type] = resource
+        resource.parsed_patterns.each do |pat|
+          patterns[pat] = resource
+        end
+      end
+
+      def populate_message_resource_lookups message, types, patterns
+        populate_resource_lookups message.resource, types, patterns if message.resource
+        message.nested_messages.each do |nested|
+          populate_message_resource_lookups nested, types, patterns
+        end
+      end
+
       def parse_parameter str
         str.scan(/\\.|,|=|[^\\,=]+/)
            .each_with_object([[String.new]]) do |tok, arr|

data/lib/gapic/schema/loader.rb

@@ -64,9 +64,13 @@ module Gapic
           load_service registry, s, address, docs, [6, i]
         end
 
+        # Load top-level resources
+        resource_descriptors = file_descriptor.options[:".google.api.resource_definition"] if file_descriptor.options
+        resources = Array(resource_descriptors).map { |descriptor| Resource.new descriptor }
+
         # Construct and return the file.
         File.new file_descriptor, address, docs[path], messages, enums,
-                 services, file_to_generate, registry
+                 services, resources, file_to_generate, registry
       end
 
       # Updates the fields of a message and it's nested messages.
@@ -158,9 +162,12 @@ module Gapic
           load_field registry, e, address, docs, path + [6, i]
         end
 
+        resource_descriptor = descriptor.options[:".google.api.resource"] if descriptor.options
+        resource = resource_descriptor ? Resource.new(resource_descriptor) : nil
+
         # Construct, cache, and return.
         msg = Message.new(descriptor, address, docs[path], fields, extensions,
-                          nested_messages, nested_enums)
+                          resource, nested_messages, nested_enums)
         @prior_messages << msg
         add_to_registry registry, address, msg
       end

data/lib/gapic/schema/wrappers.rb

@@ -357,16 +357,19 @@ module Gapic
     # Wrapper for a protobuf file.
     #
     # @!attribute [r] messages
-    #   @ return [Enumerable<Message>] The top level messages contained in
+    #   @return [Enumerable<Message>] The top level messages contained in
     #     this file.
     # @!attribute [r] enums
-    #   @ return [Enumerable<Enum>] The top level enums contained in this
+    #   @return [Enumerable<Enum>] The top level enums contained in this
     #     file.
     # @!attribute [r] services
-    #   @ return [Enumerable<Service>] The services contained in this file.
+    #   @return [Enumerable<Service>] The services contained in this file.
+    # @!attribute [r] resources
+    #   @return [Enumerable<Resource>] The top level resources contained in
+    #     this file.
     class File < Proto
       extend Forwardable
-      attr_reader :messages, :enums, :services, :registry
+      attr_reader :messages, :enums, :services, :resources, :registry
 
       # Initializes a message object.
       # @param descriptor [Google::Protobuf::DescriptorProto] the protobuf
@@ -379,20 +382,23 @@ module Gapic
       #   file.
       # @param enums [Enumerable<Enum>] The top level enums of this file.
       # @param services [Enumerable<Service>] The services of this file.
+      # @param resources [Enumerable<Resource>] The resources from this file.
       # @param generate [Boolean] Whether this file should be generated.
       def initialize descriptor, address, docs, messages, enums, services,
-                     generate, registry
+                     resources, generate, registry
         super descriptor, address, docs
         @messages = messages || []
         @enums = enums || []
         @services = services || []
+        @resources = resources || []
         @generate = generate
         @registry = registry
 
         # Apply parent
         @messages.each { |m| m.parent = self }
-        @enums.each    { |m| m.parent = self }
+        @enums.each { |m| m.parent = self }
         @services.each { |m| m.parent = self }
+        @resources.each { |m| m.parent = self }
       end
 
       def containing_file
@@ -413,13 +419,6 @@ module Gapic
         options[:ruby_package] if options
       end
 
-      # @return [Array<Google::Api::ResourceDescriptor>] A representation of the resource.
-      #   This is generally intended to be attached to the "name" field.
-      #   See `google/api/resource.proto`.
-      def resources
-        options[:".google.api.resource_definition"] if options
-      end
-
       # @!method name
       #   @return [String] file name, relative to root of source tree.
       # @!method package
@@ -511,6 +510,8 @@ module Gapic
     #   @ return [Enumerable<Field>] The fields of a message.
     # @!attribute [r] extensions
     #   @ return [Enumerable<Field>] The extensions of a message.
+    # @!attribute [r] resource
+    #   @ return [Resource,nil] A representation of the resource.
     # @!attribute [r] nested_messages
     #   @ return [Enumerable<Message>] The nested message declarations of a
     #      message.
@@ -518,7 +519,7 @@ module Gapic
     #   @ return [Enumerable<Enum>] The nested enum declarations of a message.
     class Message < Proto
       extend Forwardable
-      attr_reader :fields, :extensions, :nested_messages, :nested_enums
+      attr_reader :fields, :extensions, :resource, :nested_messages, :nested_enums
 
       # Initializes a message object.
       # @param descriptor [Google::Protobuf::DescriptorProto] the protobuf
@@ -529,15 +530,17 @@ module Gapic
       #   of the proto. See #docs for more info.
       # @param fields [Enumerable<Field>] The fields of this message.
       # @param extensions [Enumerable<Field>] The extensions of this message.
+      # @param resource [Resource,nil] The resource of this message, or nil if none.
       # @param nested_messages [Enumerable<Message>] The nested message
       #   declarations of this message.
       # @param nested_enums [Enumerable<Enum>] The nested enum declarations
       #   of this message.
-      def initialize descriptor, address, docs, fields, extensions,
+      def initialize descriptor, address, docs, fields, extensions, resource,
                      nested_messages, nested_enums
         super descriptor, address, docs
         @fields = fields || []
         @extensions = extensions || []
+        @resource = resource
         @nested_messages = nested_messages || []
         @nested_enums = nested_enums || []
 
@@ -545,13 +548,7 @@ module Gapic
         @extensions.each      { |x| x.parent = self }
         @nested_messages.each { |m| m.parent = self }
         @nested_enums.each    { |e| e.parent = self }
-      end
-
-      # @return [Google::Api::ResourceDescriptor] A representation of the resource.
-      #   This is generally intended to be attached to the "name" field.
-      #   See `google/api/resource.proto`.
-      def resource
-        options[:".google.api.resource"] if options
+        @resource.parent = self if @resource
       end
 
       # @return [Boolean] whether this type is a map entry
@@ -736,5 +733,95 @@ module Gapic
         :options
       )
     end
+
+    # Wrapper for a protobuf Resource.
+    #
+    # Unlike most wrappers, this does not subclass the {Proto} wrapper because
+    # it does not use the fields exposed by that wrapper (`address`, `docs`,
+    # etc.) This is here principally to augment the resource definition with
+    # information about resource parent-child relationships.
+    #
+    # Resource parentage is defined implicitly by path patterns. The algorithm
+    # is as follows:
+    # * If the final segment of a pattern is an ID segment (i.e. `*` or some
+    #   `{name}`) then remove it and the previous segment (which we assume to
+    #   be the corresponding collection identifier, as described in AIP-122.)
+    #   The resulting pattern is what we expect a parent to have.
+    # * If the final segment is static, then assume the pattern represents a
+    #   singleton resource (AIP-156) and remove only that one segment. The
+    #   resulting pattern is what we expect a parent to have.
+    #
+    # The {Resource#parsed_parent_patterns} method returns the set of patterns
+    # we expect of parents. It is then possible to search for resources with
+    # those patterns to determine what the parents are.
+    #
+    # @!attribute [rw] parent
+    #   @return [Gapic::Schema::File,Gapic::Schema::Message] The parent object.
+    # @!attribute [r] descriptor
+    #   @return [Array<Gapic::Schema::ResourceDescriptor>] The resource
+    #     descriptor.
+    # @!attribute [r] parsed_patterns
+    #   @return [Array<Array<String>>] The normalized, segmented forms of the
+    #     patterns. Normalized means all ID segments are replaced by asterisks
+    #     to remove non-structural differences due to different names being
+    #     used. Segmented means simply split on slashes.
+    #     For example, if a pattern is `"projects/{project}""`, the
+    #     corresponding parsed pattern would be `["projects", "*"]`.
+    # @!attribute [r] parent_resources
+    #   @return [Array<Gapic::Schema::Resource>] Parent resources
+    class Resource
+      extend Forwardable
+      attr_reader :descriptor, :parsed_patterns, :parent_resources
+      attr_accessor :parent
+
+      # Initializes a resource object.
+      # @param descriptor [Google::Protobuf::ResourceDescriptor] the protobuf
+      #   representation of this resource.
+      def initialize descriptor
+        @parent = nil
+        @descriptor = descriptor
+        @parsed_patterns = descriptor.pattern.map do |pattern|
+          pattern.split("/").map do |segment|
+            segment =~ %r{\{[^/\}]+(=[^\}]+)?\}} ? "*" : segment
+          end.freeze
+        end.freeze
+        @parent_resources = []
+      end
+
+      # Returns the "root" of this schema.
+      # @return [Gapic::Schema::Api]
+      def containing_api
+        parent&.containing_api
+      end
+
+      # Returns the file containing this proto entity
+      # @return [Gapic::Schema::File]
+      def containing_file
+        parent&.containing_file
+      end
+
+      # Returns parsed patterns for the expected parents.
+      # @return [Array<Array<String>>]
+      def parsed_parent_patterns
+        @parsed_patterns.map do |pat|
+          parent = pat.last =~ /^\*\*?$/ ? pat[0...-2] : pat[0...-1]
+          parent.empty? ? nil : parent
+        end.compact.uniq
+      end
+
+      # @!method type
+      #   @return [String] the resource type string.
+      # @!method pattern
+      #   @return [Array<String>] the set of patterns.
+      # @!method name_field
+      #   @return [String] the field on the resource that designates the
+      #     resource name field. If omitted, this is assumed to be "name".
+      def_delegators(
+        :descriptor,
+        :type,
+        :pattern,
+        :name_field
+      )
+    end
   end
 end

data/templates/default/gem/entrypoint.erb

@@ -0,0 +1,8 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+# This gem does not autoload during Bundler.require. To load this gem,
+# issue explicit require statements for the packages desired, e.g.:
+<%- gem.packages.each do |package| -%>
+# require "<%= package.package_require %>"
+<%- end -%>

data/templates/default/gem/gemspec.erb

@@ -25,7 +25,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "gapic-common", "~> 0.2"
   <%- if gem.iam_dependency? -%>
-  gem.add_dependency "grpc-google-iam-v1", "~> 0.6.9"
+  gem.add_dependency "grpc-google-iam-v1", ">= 0.6.10", "< 2.0"
   <%- end -%>
 
   gem.add_development_dependency "google-style", "~> 1.24.0"

data/templates/default/gem/readme.erb

@@ -1,4 +1,4 @@
-# <%= gem.title %>
+# Ruby Client for the <%= gem.title %> API
 
 <%= gem.summary %>
 
@@ -12,6 +12,20 @@
 $ gem install <%= gem.name %>
 ```
 
+## Quick Start
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+<%- service = gem.packages.first&.services.first -%>
+<%- method = service&.methods.first -%>
+<%- if service && method -%>
+
+client = <%= service.create_client_call %>
+request = my_create_request
+response = client.<%= method.name %> request
+<%- end -%>
+```
+
 ## Supported Ruby Versions
 
 This library is supported on Ruby 2.4+.

data/templates/default/gem/rubocop.erb

@@ -9,53 +9,25 @@ AllCops:
     - "test/**/*"
 
 Metrics/AbcSize:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
 Metrics/ClassLength:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
 Metrics/CyclomaticComplexity:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
 Metrics/LineLength:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
 Metrics/MethodLength:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
+Metrics/ModuleLength:
+  Enabled: false
 Metrics/PerceivedComplexity:
+  Enabled: false
+Naming/FileName:
   Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+    - "lib/<%= gem.name %>.rb"
 Style/CaseEquality:
-  Exclude:
-    <%- gem.packages.each do |package| -%>
-    <%- package.services.each do |service| -%>
-    - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
-    <%- end -%>
-    <%- end -%>
+  Enabled: false
+Style/IfUnlessModifier:
+  Enabled: false
 Style/ModuleFunction:
   Enabled: false

data/templates/default/lib/_package.erb

@@ -0,0 +1,17 @@
+<%- assert_locals package -%>
+<% @requires = capture do %>
+<%- package.services.each do |service| -%>
+require "<%= service.service_require %>"
+<%- end -%>
+require "<%= package.gem.version_require %>"
+<% end %>
+<%- unless package.empty? -%>
+##
+# To load this package, including all its services, and instantiate a client:
+#
+#     require "<%= package.package_require %>"
+#     client = <%= package.services.first.create_client_call %>
+#
+<%- end -%>
+module <%= package.module_name %>
+end

data/templates/default/lib/_service.erb

@@ -0,0 +1,32 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+require "gapic/common"
+require "gapic/config"
+require "gapic/config/method"
+
+require "<%= service.gem.version_require %>"
+
+require "<%= service.credentials_require %>"
+<%- if service.paths? -%>
+require "<%= service.paths_require %>"
+<%- end -%>
+<%- if service.lro? -%>
+require "<%= service.operations_require %>"
+<%- end -%>
+require "<%= service.client_require %>"
+<% end %>
+##
+<%- if service.doc_description -%>
+<%= indent service.doc_description, "# " %>
+#
+<%- end -%>
+# To load this service and instantiate a client:
+#
+#     require "<%= service.service_require %>"
+#     client = <%= service.create_client_call %>
+#
+module <%= service.module_name %>
+end
+<% @footer = capture do %>
+<%= render partial: "service/helpers", locals: { service: service} -%>
+<% end %>

data/templates/default/package.erb

@@ -1,6 +1,6 @@
 <%- assert_locals package -%>
-<%= render partial: "shared/header" -%>
-
-<% package.services.each do |service| %>
-require "<%= service.service_require %>"
-<% end %>
+<%= render partial: "lib/package",
+           layout: "layouts/ruby",
+           locals: { package: package,
+                     namespace: package.parent_namespace }
+%>

data/templates/default/service.erb

@@ -1,8 +1,6 @@
 <%- assert_locals service -%>
-<%= render partial: "shared/header" -%>
-
-require "<%= service.client_require %>"
-<%- if service.lro? -%>
-require "<%= service.operations_require %>"
-<%- end -%>
-require "<%= service.credentials_require %>"
+<%= render partial: "lib/service",
+           layout: "layouts/ruby",
+           locals: { service: service,
+                     namespace: service.namespace }
+%>

data/templates/default/service/_helpers.erb

@@ -0,0 +1,3 @@
+<%- assert_locals service -%>
+helper_path = ::File.join __dir__, "<%= service.service_directory_name%>", "helpers.rb"
+require "<%= service.helpers_require %>" if ::File.file? helper_path

data/templates/default/service/client/_client.erb

@@ -1,19 +1,7 @@
 <%- assert_locals service -%>
 <% @requires = capture do %>
-require "gapic/common"
-require "gapic/config"
-require "gapic/config/method"
-
 <%= render partial: "service/client/requires", locals: { service: service} -%>
-require "<%= service.gem.version_require %>"
 require "<%= service.proto_service_require %>"
-require "<%= service.credentials_require %>"
-<%- if service.paths? -%>
-require "<%= service.paths_require %>"
-<%- end -%>
-<%- if service.lro? -%>
-require "<%= service.operations_require %>"
-<%- end -%>
 <% end %>
 ##
 # Client for the <%= service.name %> service.
@@ -137,7 +125,3 @@ class <%= service.client_name %>
 
   <%= indent_tail render(partial: "service/client/config", locals: { service: service }), 2 %>
 end
-
-<% @footer = capture do %>
-<%= render partial: "service/client/helpers", locals: { service: service} %>
-<% end %>

data/templates/default/service/client/_operations.erb

@@ -1,10 +1,6 @@
 <%- assert_locals service -%>
 <% @requires = capture do %>
-require "gapic/common"
 require "gapic/operation"
-
-require "<%= service.gem.version_require %>"
-require "<%= service.client_require %>"
 require "<%= service.lro_service.proto_service_require %>"
 <% end %>
 # Service that implements Longrunning Operations API.

data/templates/default/service/client/_resource.erb

@@ -1,6 +1,6 @@
 <%- assert_locals resource -%>
 <%- if resource.patterns.count == 1 -%>
 <%= render partial: "service/client/resource/single", locals: { resource: resource } %>
-<%- else -%>
+<%- elsif !resource.patterns.empty? -%>
 <%= render partial: "service/client/resource/multi", locals: { resource: resource } %>
 <%- end -%>

data/templates/default/service/client/method/docs/_request_normal.erb

@@ -1,15 +1,21 @@
 <%- assert_locals method -%>
 # @overload <%= method.name %>(request, options = nil)
-#   @param request [<%= method.request_type %> | Hash]
-<%- if method.doc_description -%>
-<%= indent method.doc_description, "#     " %>
-<%- end -%>
+#   Pass arguments to `<%= method.name %>` via a request object, either of type
+#   {<%= method.request_type %>} or an equivalent Hash.
+#
+#   @param request [<%= method.request_type %>, Hash]
+#     A request object representing the call parameters. Required. To specify no
+#     parameters, or to keep all the default parameter values, pass an empty Hash.
 #   @param options [Gapic::CallOptions, Hash]
 #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
 <%-if method.arguments.any?-%>
 #
 <%- arg_list = method.arguments.map { |arg| "#{arg.name}: nil"}.join ", " -%>
 # @overload <%= method.name %>(<%= arg_list %>)
+#   Pass arguments to `<%= method.name %>` via keyword arguments. Note that at
+#   least one keyword argument is required. To specify no parameters, or to keep all
+#   the default parameter values, pass an empty Hash as a request object (see above).
+#
 <%- method.arguments.each do |arg| -%>
 #   @param <%= arg.name %> [<%= arg.doc_types %>]
 <%- if arg.doc_description -%>
@@ -17,4 +23,3 @@
 <%- end -%>
 <%- end -%>
 <%- end -%>
-#

data/templates/default/service/client/method/docs/_request_streaming.erb

@@ -1,5 +1,5 @@
 <%- assert_locals method -%>
-# @param request [Gapic::StreamInput, Enumerable<<%= method.request_type %> | Hash>]
+# @param request [Gapic::StreamInput, Enumerable<<%= method.request_type %>, Hash>]
 #   An enumerable of {<%= method.request_type %>} instances.
 # @param options [Gapic::CallOptions, Hash]
 #   Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gapic-generator
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.3
 platform: ruby
 authors:
 - Ernest Landrito
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-23 00:00:00.000000000 Z
+date: 2020-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -251,6 +251,7 @@ files:
 - lib/google/rpc/status.pb.rb
 - templates/default/gem/_version.erb
 - templates/default/gem/changelog.erb
+- templates/default/gem/entrypoint.erb
 - templates/default/gem/gemfile.erb
 - templates/default/gem/gemspec.erb
 - templates/default/gem/gitignore.erb
@@ -264,6 +265,8 @@ files:
 - templates/default/helpers/filepath_helper.rb
 - templates/default/helpers/namespace_helper.rb
 - templates/default/layouts/_ruby.erb
+- templates/default/lib/_package.erb
+- templates/default/lib/_service.erb
 - templates/default/package.erb
 - templates/default/proto_docs/_enum.erb
 - templates/default/proto_docs/_message.erb
@@ -271,11 +274,11 @@ files:
 - templates/default/proto_docs/proto_file.erb
 - templates/default/proto_docs/readme.erb
 - templates/default/service.erb
+- templates/default/service/_helpers.erb
 - templates/default/service/client.erb
 - templates/default/service/client/_client.erb
 - templates/default/service/client/_config.erb
 - templates/default/service/client/_credentials.erb
-- templates/default/service/client/_helpers.erb
 - templates/default/service/client/_operations.erb
 - templates/default/service/client/_paths.erb
 - templates/default/service/client/_requires.erb

data/templates/default/service/client/_helpers.erb

@@ -1,9 +0,0 @@
-# rubocop:disable Lint/HandleExceptions
-
-# Once client is loaded, load helpers.rb if it exists.
-begin
-  require "<%= service.helpers_require %>"
-rescue LoadError
-end
-
-# rubocop:enable Lint/HandleExceptions