fix: docs for oneof parameters (#1207)

* fix: docs for oneof parameters

Author: viacheslav-rostovtsev

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

@@ -72,8 +72,8 @@ def output_doc_types
       #   gRPC client classes. Uses the default transport if not provided.
       # @return [String]
       #
-      def doc_description transport: nil
-        @field.docs_leading_comments transport: transport
+      def doc_description transport: nil, is_rpc_param: false
+        @field.docs_leading_comments transport: transport, is_rpc_param: is_rpc_param
       end
 
       def default_value

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

@@ -983,16 +983,22 @@ def populate_oneof_siblings! all_fields
 
       # @private
       # Override this to add a note related to oneofs being mutually exclusive.
-      def docs_leading_comments disable_xrefs: false, transport: nil
-        str = super
+      def docs_leading_comments disable_xrefs: false, transport: nil, is_rpc_param: false
+        str = super(disable_xrefs: disable_xrefs, transport: transport)
         return str unless @oneof_siblings && @oneof_siblings.size > 1
         siblings = @oneof_siblings.map { |field| "`#{field.name}`" }.join ", "
-        note = "Note: The following fields are mutually exclusive: " \
-               "#{siblings}. If a field in that set is populated, all other " \
-               "fields in the set will automatically be cleared."
+        note =
+          if is_rpc_param
+            "Note: The following parameters are mutually exclusive: #{siblings}. " \
+              "At most one of these parameters can be set. If more than one is set, " \
+              "only one will be used, and it is not defined which one."
+          else
+            "Note: The following fields are mutually exclusive: #{siblings}. " \
+              "If a field in that set is populated, all other fields in the set " \
+              "will automatically be cleared."
+          end
         str ? "#{str.strip}\n\n#{note}" : note
       end
-
       # @!method name
       #   @return [String] the unqualified name of the field.
       # @!method number

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

@@ -19,7 +19,7 @@
 <%- method.arguments.each do |arg| -%>
 #   @param <%= arg.name %> [<%= arg.doc_types %>]
 <%- if arg.doc_description -%>
-<%= indent arg.doc_description(transport: :grpc), "#     " %>
+<%= indent arg.doc_description(transport: :grpc, is_rpc_param: true), "#     " %>
 <%- end -%>
 <%- end -%>
 <%- end -%>

gapic-generator/templates/default/service/rest/client/method/docs/_request.text.erb

@@ -19,7 +19,7 @@
 <%- method.arguments.each do |arg| -%>
 #   @param <%= arg.name %> [<%= arg.doc_types %>]
 <%- if arg.doc_description -%>
-<%= indent arg.doc_description(transport: :rest), "#     " %>
+<%= indent arg.doc_description(transport: :rest, is_rpc_param: true), "#     " %>
 <%- end -%>
 <%- end -%>
 <%- end -%>

gapic-generator/test/gapic/presenters/field_presenter_test.rb

@@ -141,6 +141,11 @@ def test_typical_garbage_oneof_enum_field
       "`oneof_multiple_bytes`, `oneof_multiple_double`. If a field in that set is populated, all other fields in " \
       "the set will automatically be cleared."
     assert_equal expected_description, fp.doc_description
+    expected_description_rpc_params = "This is a multiple-field oneof's enum field.\n\n" \
+      "Note: The following parameters are mutually exclusive: `oneof_multiple_enum`, `oneof_multiple_message`, " \
+      "`oneof_multiple_bytes`, `oneof_multiple_double`. At most one of these parameters can be set. If more than one is set, " \
+      "only one will be used, and it is not defined which one."
+    assert_equal expected_description_rpc_params, fp.doc_description(is_rpc_param: true)
     assert_equal ":DEFAULT_GARBAGE", fp.default_value
     assert_equal ".endless.trash.forever.GarbageEnum", fp.type_name
     assert_equal "::So::Much::Trash::GarbageEnum", fp.type_name_full

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

@@ -2061,12 +2061,12 @@ def import_product_sets request, options = nil
             #   @param product_set_purge_config [::Google::Cloud::Vision::V1::ProductSetPurgeConfig, ::Hash]
             #     Specify which ProductSet contains the Products to be deleted.
             #
-            #     Note: The following fields are mutually exclusive: `product_set_purge_config`, `delete_orphan_products`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+            #     Note: The following parameters are mutually exclusive: `product_set_purge_config`, `delete_orphan_products`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
             #   @param delete_orphan_products [::Boolean]
             #     If delete_orphan_products is true, all Products that are not in any
             #     ProductSet will be deleted.
             #
-            #     Note: The following fields are mutually exclusive: `delete_orphan_products`, `product_set_purge_config`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+            #     Note: The following parameters are mutually exclusive: `delete_orphan_products`, `product_set_purge_config`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
             #   @param parent [::String]
             #     Required. The project and location in which the Products should be deleted.
             #

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

@@ -1929,12 +1929,12 @@ def import_product_sets request, options = nil
               #   @param product_set_purge_config [::Google::Cloud::Vision::V1::ProductSetPurgeConfig, ::Hash]
               #     Specify which ProductSet contains the Products to be deleted.
               #
-              #     Note: The following fields are mutually exclusive: `product_set_purge_config`, `delete_orphan_products`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+              #     Note: The following parameters are mutually exclusive: `product_set_purge_config`, `delete_orphan_products`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
               #   @param delete_orphan_products [::Boolean]
               #     If delete_orphan_products is true, all Products that are not in any
               #     ProductSet will be deleted.
               #
-              #     Note: The following fields are mutually exclusive: `delete_orphan_products`, `product_set_purge_config`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+              #     Note: The following parameters are mutually exclusive: `delete_orphan_products`, `product_set_purge_config`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
               #   @param parent [::String]
               #     Required. The project and location in which the Products should be deleted.
               #

shared/output/gapic/templates/garbage/lib/so/much/trash/garbage_service/client.rb

@@ -717,27 +717,27 @@ def get_repeated_garbage request, options = nil
           #   @param oneof_pair_int32 [::Integer]
           #     This is a pair oneof's int32 field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_pair_int32`, `oneof_pair_float`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_pair_int32`, `oneof_pair_float`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param oneof_pair_float [::Float]
           #     This is a pair oneof's float field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_pair_float`, `oneof_pair_int32`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_pair_float`, `oneof_pair_int32`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param oneof_multiple_message [::So::Much::Trash::SimpleGarbageItem, ::Hash]
           #     This is a multiple-field oneof's message field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_enum`, `oneof_multiple_double`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_enum`, `oneof_multiple_double`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param oneof_multiple_bytes [::String]
           #     This is a multiple-field oneof's bytes field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_multiple_bytes`, `oneof_multiple_message`, `oneof_multiple_enum`, `oneof_multiple_double`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_multiple_bytes`, `oneof_multiple_message`, `oneof_multiple_enum`, `oneof_multiple_double`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param oneof_multiple_enum [::So::Much::Trash::GarbageEnum]
           #     This is a multiple-field oneof's enum field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_multiple_enum`, `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_double`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_multiple_enum`, `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_double`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param oneof_multiple_double [::Float]
           #     This is a multiple-field oneof's double field.
           #
-          #     Note: The following fields are mutually exclusive: `oneof_multiple_double`, `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_enum`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `oneof_multiple_double`, `oneof_multiple_message`, `oneof_multiple_bytes`, `oneof_multiple_enum`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param optional_int32 [::Integer]
           #   @param case [::String]
           #     This field tests for collisions against Ruby reserved keywords.

shared/output/gapic/templates/showcase/lib/google/showcase/v1beta1/echo/client.rb

@@ -254,11 +254,11 @@ def logger
           #   @param content [::String]
           #     The content to be echoed by the server.
           #
-          #     Note: The following fields are mutually exclusive: `content`, `error`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `content`, `error`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param error [::Google::Rpc::Status, ::Hash]
           #     The error to be thrown by the server.
           #
-          #     Note: The following fields are mutually exclusive: `error`, `content`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `error`, `content`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param severity [::Google::Showcase::V1beta1::Severity]
           #     The severity to be echoed by the server.
           #   @param header [::String]
@@ -982,20 +982,20 @@ def paged_expand_legacy_mapped request, options = nil
           #   @param end_time [::Google::Protobuf::Timestamp, ::Hash]
           #     The time that this operation will complete.
           #
-          #     Note: The following fields are mutually exclusive: `end_time`, `ttl`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `end_time`, `ttl`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param ttl [::Google::Protobuf::Duration, ::Hash]
           #     The duration of this operation.
           #
-          #     Note: The following fields are mutually exclusive: `ttl`, `end_time`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `ttl`, `end_time`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param error [::Google::Rpc::Status, ::Hash]
           #     The error that will be returned by the server. If this code is specified
           #     to be the OK rpc code, an empty response will be returned.
           #
-          #     Note: The following fields are mutually exclusive: `error`, `success`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `error`, `success`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param success [::Google::Showcase::V1beta1::WaitResponse, ::Hash]
           #     The response to be returned on operation completion.
           #
-          #     Note: The following fields are mutually exclusive: `success`, `error`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `success`, `error`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #
           # @yield [response, operation] Access the result along with the RPC operation
           # @yieldparam response [::Gapic::Operation]
@@ -1086,11 +1086,11 @@ def wait request, options = nil
           #     The error that will be returned by the server. If this code is specified
           #     to be the OK rpc code, an empty response will be returned.
           #
-          #     Note: The following fields are mutually exclusive: `error`, `success`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `error`, `success`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #   @param success [::Google::Showcase::V1beta1::BlockResponse, ::Hash]
           #     The response to be returned that will signify successful method call.
           #
-          #     Note: The following fields are mutually exclusive: `success`, `error`. If a field in that set is populated, all other fields in the set will automatically be cleared.
+          #     Note: The following parameters are mutually exclusive: `success`, `error`. At most one of these parameters can be set. If more than one is set, only one will be used, and it is not defined which one.
           #
           # @yield [response, operation] Access the result along with the RPC operation
           # @yieldparam response [::Google::Showcase::V1beta1::BlockResponse]