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

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,32 @@ 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. As a best " \
+               "practice, explicitly clear any existing field first, by " \
+               "setting it to `nil`, before populating another."
+        str ? "#{str.strip}\n\n#{note}" : note
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the field.
       # @!method number