feat(gapic-generator): Add clarifying notes to oneof members in proto_docs (#1142)

Author: dazuma

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

@@ -190,6 +190,7 @@ def load_message registry, descriptor, address, docs, path
         fields = (descriptor.field || []).each_with_index.map do |f, i|
           load_field registry, f, address, docs, path + [2, i]
         end
+        fields.each { |field| field.populate_oneof_siblings! fields }
         extensions = (descriptor.extension || []).each_with_index.map do |e, i|
           load_field registry, e, address, docs, path + [6, i]
         end

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

@@ -761,6 +761,7 @@ def initialize descriptor, address, docs, message, enum
         super descriptor, address, docs
         @message = message
         @enum = enum
+        @oneof_siblings = nil
       end
 
       OPTION_EXTENSION_NAMES = {
@@ -968,6 +969,30 @@ def is_deprecated?
         option_named "deprecated"
       end
 
+      # @private
+      # Populate the oneof_siblings array. This is nil if this field is not part
+      # of a oneof, otherwise it's an array of fields that are members of the
+      # oneof, with the first element being the current field.
+      def populate_oneof_siblings! all_fields
+        return unless oneof?
+        @oneof_siblings = [self]
+        all_fields.each do |field|
+          @oneof_siblings << field if field != self && field.oneof? && field.oneof_index == oneof_index
+        end
+      end
+
+      # @private
+      # Override this to add a note related to oneofs being mutually exclusive.
+      def docs_leading_comments disable_xrefs: false, transport: nil
+        str = super
+        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."
+        str ? "#{str.strip}\n\n#{note}" : note
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the field.
       # @!method number

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

@@ -136,7 +136,11 @@ def test_typical_garbage_oneof_enum_field
     assert_equal "oneof_multiple_enum", fp.name
     assert_equal "@!attribute [rw] oneof_multiple_enum", fp.doc_attribute_type
     assert_equal "::So::Much::Trash::GarbageEnum", fp.output_doc_types
-    assert_equal fp.doc_description, "This is a multiple-field oneof's enum field.\n"
+    expected_description = "This is a multiple-field oneof's enum field.\n\n" \
+      "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."
+    assert_equal expected_description, fp.doc_description
     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/ads/googleads/proto_docs/google/ads/googleads/v15/resources/campaign.rb

@@ -267,60 +267,88 @@ module Resources
           # @!attribute [rw] bidding_strategy
           #   @return [::String]
           #     Portfolio bidding strategy used by campaign.
+          #
+          #     Note: The following fields are mutually exclusive: `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] commission
           #   @return [::Google::Ads::GoogleAds::V15::Common::Commission]
           #     Commission is an automatic bidding strategy in which the advertiser pays
           #     a certain portion of the conversion value.
+          #
+          #     Note: The following fields are mutually exclusive: `commission`, `bidding_strategy`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] manual_cpa
           #   @return [::Google::Ads::GoogleAds::V15::Common::ManualCpa]
           #     Standard Manual CPA bidding strategy.
           #     Manual bidding strategy that allows advertiser to set the bid per
           #     advertiser-specified action. Supported only for Local Services campaigns.
+          #
+          #     Note: The following fields are mutually exclusive: `manual_cpa`, `bidding_strategy`, `commission`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] manual_cpc
           #   @return [::Google::Ads::GoogleAds::V15::Common::ManualCpc]
           #     Standard Manual CPC bidding strategy.
           #     Manual click-based bidding where user pays per click.
+          #
+          #     Note: The following fields are mutually exclusive: `manual_cpc`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] manual_cpm
           #   @return [::Google::Ads::GoogleAds::V15::Common::ManualCpm]
           #     Standard Manual CPM bidding strategy.
           #     Manual impression-based bidding where user pays per thousand
           #     impressions.
+          #
+          #     Note: The following fields are mutually exclusive: `manual_cpm`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] manual_cpv
           #   @return [::Google::Ads::GoogleAds::V15::Common::ManualCpv]
           #     A bidding strategy that pays a configurable amount per video view.
+          #
+          #     Note: The following fields are mutually exclusive: `manual_cpv`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] maximize_conversions
           #   @return [::Google::Ads::GoogleAds::V15::Common::MaximizeConversions]
           #     Standard Maximize Conversions bidding strategy that automatically
           #     maximizes number of conversions while spending your budget.
+          #
+          #     Note: The following fields are mutually exclusive: `maximize_conversions`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] maximize_conversion_value
           #   @return [::Google::Ads::GoogleAds::V15::Common::MaximizeConversionValue]
           #     Standard Maximize Conversion Value bidding strategy that automatically
           #     sets bids to maximize revenue while spending your budget.
+          #
+          #     Note: The following fields are mutually exclusive: `maximize_conversion_value`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] target_cpa
           #   @return [::Google::Ads::GoogleAds::V15::Common::TargetCpa]
           #     Standard Target CPA bidding strategy that automatically sets bids to
           #     help get as many conversions as possible at the target
           #     cost-per-acquisition (CPA) you set.
+          #
+          #     Note: The following fields are mutually exclusive: `target_cpa`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] target_impression_share
           #   @return [::Google::Ads::GoogleAds::V15::Common::TargetImpressionShare]
           #     Target Impression Share bidding strategy. An automated bidding strategy
           #     that sets bids to achieve a chosen percentage of impressions.
+          #
+          #     Note: The following fields are mutually exclusive: `target_impression_share`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_roas`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] target_roas
           #   @return [::Google::Ads::GoogleAds::V15::Common::TargetRoas]
           #     Standard Target ROAS bidding strategy that automatically maximizes
           #     revenue while averaging a specific target return on ad spend (ROAS).
+          #
+          #     Note: The following fields are mutually exclusive: `target_roas`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_spend`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] target_spend
           #   @return [::Google::Ads::GoogleAds::V15::Common::TargetSpend]
           #     Standard Target Spend bidding strategy that automatically sets your bids
           #     to help get as many clicks as possible within your budget.
+          #
+          #     Note: The following fields are mutually exclusive: `target_spend`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `percent_cpc`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] percent_cpc
           #   @return [::Google::Ads::GoogleAds::V15::Common::PercentCpc]
           #     Standard Percent Cpc bidding strategy where bids are a fraction of the
           #     advertised price for some good or service.
+          #
+          #     Note: The following fields are mutually exclusive: `percent_cpc`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `target_cpm`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] target_cpm
           #   @return [::Google::Ads::GoogleAds::V15::Common::TargetCpm]
           #     A bidding strategy that automatically optimizes cost per thousand
           #     impressions.
+          #
+          #     Note: The following fields are mutually exclusive: `target_cpm`, `bidding_strategy`, `commission`, `manual_cpa`, `manual_cpc`, `manual_cpm`, `manual_cpv`, `maximize_conversions`, `maximize_conversion_value`, `target_cpa`, `target_impression_share`, `target_roas`, `target_spend`, `percent_cpc`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           class Campaign
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods

shared/output/ads/googleads/proto_docs/google/ads/googleads/v15/services/campaign_service.rb

@@ -56,16 +56,22 @@ class MutateCampaignsRequest
           # @!attribute [rw] create
           #   @return [::Google::Ads::GoogleAds::V15::Resources::Campaign]
           #     Create operation: No resource name is expected for the new campaign.
+          #
+          #     Note: The following fields are mutually exclusive: `create`, `update`, `remove`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] update
           #   @return [::Google::Ads::GoogleAds::V15::Resources::Campaign]
           #     Update operation: The campaign is expected to have a valid
           #     resource name.
+          #
+          #     Note: The following fields are mutually exclusive: `update`, `create`, `remove`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           # @!attribute [rw] remove
           #   @return [::String]
           #     Remove operation: A resource name for the removed campaign is
           #     expected, in this format:
           #
           #     `customers/{customer_id}/campaigns/{campaign_id}`
+          #
+          #     Note: The following fields are mutually exclusive: `remove`, `create`, `update`. If a field in that set is populated, all other fields in the set will automatically be cleared.
           class CampaignOperation
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods

shared/output/cloud/grafeas_v1/proto_docs/google/protobuf/struct.rb

@@ -53,21 +53,33 @@ class FieldsEntry
     # @!attribute [rw] null_value
     #   @return [::Google::Protobuf::NullValue]
     #     Represents a null value.
+    #
+    #     Note: The following fields are mutually exclusive: `null_value`, `number_value`, `string_value`, `bool_value`, `struct_value`, `list_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     # @!attribute [rw] number_value
     #   @return [::Float]
     #     Represents a double value.
+    #
+    #     Note: The following fields are mutually exclusive: `number_value`, `null_value`, `string_value`, `bool_value`, `struct_value`, `list_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     # @!attribute [rw] string_value
     #   @return [::String]
     #     Represents a string value.
+    #
+    #     Note: The following fields are mutually exclusive: `string_value`, `null_value`, `number_value`, `bool_value`, `struct_value`, `list_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     # @!attribute [rw] bool_value
     #   @return [::Boolean]
     #     Represents a boolean value.
+    #
+    #     Note: The following fields are mutually exclusive: `bool_value`, `null_value`, `number_value`, `string_value`, `struct_value`, `list_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     # @!attribute [rw] struct_value
     #   @return [::Google::Protobuf::Struct]
     #     Represents a structured value.
+    #
+    #     Note: The following fields are mutually exclusive: `struct_value`, `null_value`, `number_value`, `string_value`, `bool_value`, `list_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     # @!attribute [rw] list_value
     #   @return [::Google::Protobuf::ListValue]
     #     Represents a repeated `Value`.
+    #
+    #     Note: The following fields are mutually exclusive: `list_value`, `null_value`, `number_value`, `string_value`, `bool_value`, `struct_value`. If a field in that set is populated, all other fields in the set will automatically be cleared.
     class Value
       include ::Google::Protobuf::MessageExts
       extend ::Google::Protobuf::MessageExts::ClassMethods