feat: Generate inline snippets in yardoc

gapic-generator-cloud/lib/gapic/generators/cloud_generator_parameters.rb

@@ -21,10 +21,12 @@ module Generators
     # Contains the cloud generator's parameters
     module CloudGeneratorParameters
       BOOL_PARAMETERS_ALIASES = {
-        "ruby-cloud-free-tier"         => ":gem.:free_tier",
-        "ruby-cloud-yard-strict"       => ":gem.:yard_strict",
-        "ruby-cloud-generic-endpoint"  => ":gem.:generic_endpoint",
-        "ruby-cloud-generate-metadata" => ":generate_metadata"
+        "ruby-cloud-free-tier"                    => ":gem.:free_tier",
+        "ruby-cloud-yard-strict"                  => ":gem.:yard_strict",
+        "ruby-cloud-generic-endpoint"             => ":gem.:generic_endpoint",
+        "ruby-cloud-generate-metadata"            => ":generate_metadata",
+        "ruby-cloud-generate-standalone-snippets" => ":generate_standalone_snippets",
+        "ruby-cloud-generate-yardoc-snippets"     => ":generate_yardoc_snippets"
       }.freeze
 
       STRING_PARAMETERS_ALIASES = {

gapic-generator/lib/gapic/generators/default_generator_parameters.rb

@@ -24,7 +24,9 @@ module DefaultGeneratorParameters
         ":gem.:free_tier",
         ":gem.:yard_strict",
         ":gem.:generic_endpoint",
-        ":generate_metadata"
+        ":generate_metadata",
+        ":generate_standalone_snippets",
+        ":generate_yardoc_snippets"
       ].freeze
 
       STRING_PARAMETERS = [

gapic-generator/lib/gapic/presenters/method_presenter.rb

@@ -54,6 +54,10 @@ def snippet
         SnippetPresenter.new self, @api
       end
 
+      def generate_yardoc_snippets?
+        @api.generate_yardoc_snippets?
+      end
+
       def name
         @name ||= begin
           candidate = ActiveSupport::Inflector.underscore @method.name

gapic-generator/lib/gapic/presenters/snippet_presenter.rb

@@ -52,7 +52,7 @@ def snippet_file_path
       end
 
       def require_path
-        @method_presenter.service.service_require
+        @method_presenter.service.package.package_require
       end
 
       def client_type

gapic-generator/lib/gapic/schema/api.rb

@@ -250,6 +250,11 @@ def generate_standalone_snippets?
         configuration[:generate_standalone_snippets] ||= false
       end
 
+      # Whether to generate inline documentation snippets
+      def generate_yardoc_snippets?
+        configuration[:generate_yardoc_snippets] ||= false
+      end
+
       # Whether to generate gapic metadata (drift manifest) file
       # @return [Boolean]
       def generate_metadata

gapic-generator/templates/default/service/client/method/_def.erb

@@ -10,6 +10,7 @@
 #
 <%= render partial: "service/client/method/docs/error", locals: { method: method } -%>
 #
+<%= render partial: "service/client/method/docs/snippets", locals: { method: method } -%>
 <%= render partial: "service/client/method/docs/samples", locals: { method: method } -%>
 def <%= method.name %> request, options = nil
 <%= indent render(partial: "service/client/method/def/request", locals: { method: method }), 2 %>

gapic-generator/templates/default/service/client/method/docs/_snippets.erb

@@ -0,0 +1,6 @@
+<%- assert_locals method -%>
+<%- if method.generate_yardoc_snippets? -%>
+# @example Basic example
+<%= indent render(partial: "snippets/snippet/structure", locals: { snippet: method.snippet }), "#   " %>
+#
+<%- end -%>

shared/config/vision_v1.yml

@@ -12,3 +12,4 @@
       - https://www.googleapis.com/auth/cloud-vision
 :generate_metadata: false
 :generate_standalone_snippets: true
+:generate_yardoc_snippets: true

shared/output/cloud/vision_v1/lib/google/cloud/vision/v1/image_annotator/client.rb

@@ -206,6 +206,21 @@ def initialize
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/vision/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Vision::V1::ImageAnnotator::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Vision::V1::BatchAnnotateImagesRequest.new
+            #
+            #   # Call the batch_annotate_images method.
+            #   result = client.batch_annotate_images request
+            #
+            #   # The returned object is of type Google::Cloud::Vision::V1::BatchAnnotateImagesResponse.
+            #   p result
+            #
             def batch_annotate_images request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -286,6 +301,21 @@ def batch_annotate_images request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/vision/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Vision::V1::ImageAnnotator::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Vision::V1::BatchAnnotateFilesRequest.new
+            #
+            #   # Call the batch_annotate_files method.
+            #   result = client.batch_annotate_files request
+            #
+            #   # The returned object is of type Google::Cloud::Vision::V1::BatchAnnotateFilesResponse.
+            #   p result
+            #
             def batch_annotate_files request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -369,6 +399,28 @@ def batch_annotate_files request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/vision/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Vision::V1::ImageAnnotator::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Vision::V1::AsyncBatchAnnotateImagesRequest.new
+            #
+            #   # Call the async_batch_annotate_images method.
+            #   result = client.async_batch_annotate_images request
+            #
+            #   # The returned object is of type Gapic::Operation. You can use this
+            #   # object to check the status of an operation, cancel it, or wait
+            #   # for results. Here is how to block until completion:
+            #   result.wait_until_done! timeout: 60
+            #   if result.response?
+            #     p result.response
+            #   else
+            #     puts "Error!"
+            #   end
+            #
             def async_batch_annotate_images request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -448,6 +500,28 @@ def async_batch_annotate_images request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/vision/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Vision::V1::ImageAnnotator::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Vision::V1::AsyncBatchAnnotateFilesRequest.new
+            #
+            #   # Call the async_batch_annotate_files method.
+            #   result = client.async_batch_annotate_files request
+            #
+            #   # The returned object is of type Gapic::Operation. You can use this
+            #   # object to check the status of an operation, cancel it, or wait
+            #   # for results. Here is how to block until completion:
+            #   result.wait_until_done! timeout: 60
+            #   if result.response?
+            #     p result.response
+            #   else
+            #     puts "Error!"
+            #   end
+            #
             def async_batch_annotate_files request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 

shared/output/cloud/vision_v1/lib/google/cloud/vision/v1/image_annotator/operations.rb

@@ -138,6 +138,27 @@ def initialize
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/longrunning"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Longrunning::Operations::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Longrunning::ListOperationsRequest.new
+            #
+            #   # Call the list_operations method.
+            #   result = client.list_operations request
+            #
+            #   # The returned object is of type Gapic::PagedEnumerable. You can
+            #   # iterate over all elements by calling #each, and the enumerable
+            #   # will lazily make API calls to fetch subsequent pages. Other
+            #   # methods are also available for managing paging directly.
+            #   result.each do |response|
+            #     # Each element is of type ::Google::Longrunning::Operation.
+            #     p response
+            #   end
+            #
             def list_operations request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -208,6 +229,28 @@ def list_operations request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/longrunning"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Longrunning::Operations::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Longrunning::GetOperationRequest.new
+            #
+            #   # Call the get_operation method.
+            #   result = client.get_operation request
+            #
+            #   # The returned object is of type Gapic::Operation. You can use this
+            #   # object to check the status of an operation, cancel it, or wait
+            #   # for results. Here is how to block until completion:
+            #   result.wait_until_done! timeout: 60
+            #   if result.response?
+            #     p result.response
+            #   else
+            #     puts "Error!"
+            #   end
+            #
             def get_operation request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -278,6 +321,21 @@ def get_operation request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/longrunning"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Longrunning::Operations::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Longrunning::DeleteOperationRequest.new
+            #
+            #   # Call the delete_operation method.
+            #   result = client.delete_operation request
+            #
+            #   # The returned object is of type Google::Protobuf::Empty.
+            #   p result
+            #
             def delete_operation request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -353,6 +411,21 @@ def delete_operation request, options = nil
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/longrunning"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Longrunning::Operations::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Longrunning::CancelOperationRequest.new
+            #
+            #   # Call the cancel_operation method.
+            #   result = client.cancel_operation request
+            #
+            #   # The returned object is of type Google::Protobuf::Empty.
+            #   p result
+            #
             def cancel_operation request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?