fix: list oneofs in docstring (#1030)

* fix: list oneofs in docstring

* chore: copy to ads templates

* docs: remove separate list in docstring

* chore: also update ads

gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2

@@ -2,10 +2,25 @@ class {{ message.name }}({{ p }}.Message):
     r"""{{ message.meta.doc|rst(indent=4) }}
     {% if message.fields|length %}
 
+    {# Only include note if a oneof has more than one member field. #}
+    {% if message.oneof_fields() %}
+    {% if message.oneof_fields().values() | map('length') | max > 1 %}
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    {% endif %}
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    {% endif %}
     Attributes:
     {% for field in message.fields.values() %}
         {{ field.name }} ({{ field.ident.sphinx }}):
             {{ field.meta.doc|rst(indent=12, nl=False) }}
+            {% if field.oneof %}
+            This field is a member of `oneof`_ ``{{ field.oneof }}``.
+            {% endif %}
     {% endfor %}
     {% endif %}
     """

gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2

@@ -2,10 +2,25 @@ class {{ message.name }}({{ p }}.Message):
     r"""{{ message.meta.doc|rst(indent=4) }}
     {% if message.fields|length %}
 
+    {# Only include note if a oneof has more than one member field. #}
+    {% if message.oneof_fields() %}
+    {% if message.oneof_fields().values() | map('length') | max > 1 %}
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    {% endif %}
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    {% endif %}
     Attributes:
     {% for field in message.fields.values() %}
         {{ field.name }} ({{ field.ident.sphinx }}):
             {{ field.meta.doc|rst(indent=12, nl=False) }}
+            {% if field.oneof %}
+            This field is a member of `oneof`_ ``{{ field.oneof }}``.
+            {% endif %}
     {% endfor %}
     {% endif %}
     """

tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py

@@ -512,13 +512,22 @@ class DeleteFeedRequest(proto.Message):
 class OutputConfig(proto.Message):
     r"""Output configuration for export assets destination.
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         gcs_destination (google.cloud.asset_v1.types.GcsDestination):
             Destination on Cloud Storage.
+            This field is a member of `oneof`_ ``destination``.
         bigquery_destination (google.cloud.asset_v1.types.BigQueryDestination):
             Destination on BigQuery. The output table
             stores the fields in asset proto as columns in
             BigQuery.
+            This field is a member of `oneof`_ ``destination``.
     """
 
     gcs_destination = proto.Field(
@@ -538,9 +547,12 @@ class OutputConfig(proto.Message):
 class OutputResult(proto.Message):
     r"""Output result of export assets.
 
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         gcs_result (google.cloud.asset_v1.types.GcsOutputResult):
             Export result on Cloud Storage.
+            This field is a member of `oneof`_ ``result``.
     """
 
     gcs_result = proto.Field(
@@ -569,6 +581,13 @@ class GcsOutputResult(proto.Message):
 class GcsDestination(proto.Message):
     r"""A Cloud Storage location.
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         uri (str):
             The uri of the Cloud Storage object. It's the same uri that
@@ -581,6 +600,7 @@ class GcsDestination(proto.Message):
             there is no
             `hold <https://cloud.google.com/storage/docs/object-holds>`__,
             it will be overwritten with the exported result.
+            This field is a member of `oneof`_ ``object_uri``.
         uri_prefix (str):
             The uri prefix of all generated Cloud Storage objects.
             Example: "gs://bucket_name/object_name_prefix". Each object
@@ -591,6 +611,7 @@ class GcsDestination(proto.Message):
             compute.googleapis.com/Disk assets. An INVALID_ARGUMENT
             error will be returned if file with the same name
             "gs://bucket_name/object_name_prefix" already exists.
+            This field is a member of `oneof`_ ``object_uri``.
     """
 
     uri = proto.Field(
@@ -751,9 +772,12 @@ class PubsubDestination(proto.Message):
 class FeedOutputConfig(proto.Message):
     r"""Output configuration for asset feed destination.
 
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         pubsub_destination (google.cloud.asset_v1.types.PubsubDestination):
             Destination on Pub/Sub.
+            This field is a member of `oneof`_ ``destination``.
     """
 
     pubsub_destination = proto.Field(
@@ -1420,12 +1444,15 @@ class Options(proto.Message):
     class ConditionContext(proto.Message):
         r"""The IAM conditions context.
 
+        .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
         Attributes:
             access_time (google.protobuf.timestamp_pb2.Timestamp):
                 The hypothetical access timestamp to evaluate IAM
                 conditions. Note that this value must not be earlier than
                 the current time; otherwise, an INVALID_ARGUMENT error will
                 be returned.
+                This field is a member of `oneof`_ ``TimeContext``.
         """
 
         access_time = proto.Field(
@@ -1580,11 +1607,20 @@ class IamPolicyAnalysisOutputConfig(proto.Message):
     r"""Output configuration for export IAM policy analysis
     destination.
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         gcs_destination (google.cloud.asset_v1.types.IamPolicyAnalysisOutputConfig.GcsDestination):
             Destination on Cloud Storage.
+            This field is a member of `oneof`_ ``destination``.
         bigquery_destination (google.cloud.asset_v1.types.IamPolicyAnalysisOutputConfig.BigQueryDestination):
             Destination on BigQuery.
+            This field is a member of `oneof`_ ``destination``.
     """
 
     class GcsDestination(proto.Message):

tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py

@@ -131,6 +131,13 @@ class Asset(proto.Message):
     types <https://cloud.google.com/asset-inventory/docs/supported-asset-types>`__
     for more information.
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         update_time (google.protobuf.timestamp_pb2.Timestamp):
             The last update timestamp of an asset. update_time is
@@ -171,12 +178,15 @@ class Asset(proto.Message):
         access_policy (google.identity.accesscontextmanager.v1.access_policy_pb2.AccessPolicy):
             Please also refer to the `access policy user
             guide <https://cloud.google.com/access-context-manager/docs/overview#access-policies>`__.
+            This field is a member of `oneof`_ ``access_context_policy``.
         access_level (google.identity.accesscontextmanager.v1.access_level_pb2.AccessLevel):
             Please also refer to the `access level user
             guide <https://cloud.google.com/access-context-manager/docs/overview#access-levels>`__.
+            This field is a member of `oneof`_ ``access_context_policy``.
         service_perimeter (google.identity.accesscontextmanager.v1.service_perimeter_pb2.ServicePerimeter):
             Please also refer to the `service perimeter user
             guide <https://cloud.google.com/vpc-service-controls/docs/overview>`__.
+            This field is a member of `oneof`_ ``access_context_policy``.
         os_inventory (google.cloud.osconfig.v1.inventory_pb2.Inventory):
             A representation of runtime OS Inventory information. See
             `this
@@ -882,11 +892,20 @@ class Resource(proto.Message):
     class Access(proto.Message):
         r"""An IAM role or permission under analysis.
 
+        This message has `oneof`_ fields (mutually exclusive fields).
+        For each oneof, at most one member field can be set at the same time.
+        Setting any member of the oneof automatically clears all other
+        members.
+
+        .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
         Attributes:
             role (str):
                 The role.
+                This field is a member of `oneof`_ ``oneof_access``.
             permission (str):
                 The permission.
+                This field is a member of `oneof`_ ``oneof_access``.
             analysis_state (google.cloud.asset_v1.types.IamPolicyAnalysisState):
                 The analysis state of this access.
         """

tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py

@@ -36,6 +36,13 @@
 class LogEntry(proto.Message):
     r"""An individual entry in a log.
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         log_name (str):
             Required. The resource name of the log to which this log
@@ -84,12 +91,15 @@ class LogEntry(proto.Message):
 
             "type.googleapis.com/google.cloud.audit.AuditLog"
             "type.googleapis.com/google.appengine.logging.v1.RequestLog".
+            This field is a member of `oneof`_ ``payload``.
         text_payload (str):
             The log entry payload, represented as a
             Unicode string (UTF-8).
+            This field is a member of `oneof`_ ``payload``.
         json_payload (google.protobuf.struct_pb2.Struct):
             The log entry payload, represented as a
             structure that is expressed as a JSON object.
+            This field is a member of `oneof`_ ``payload``.
         timestamp (google.protobuf.timestamp_pb2.Timestamp):
             Optional. The time the event described by the log entry
             occurred. This time is used to compute the log entry's age

tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py

@@ -195,6 +195,9 @@ class LogSink(proto.Message):
     created within a project, organization, billing account, or
     folder.
 
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         name (str):
             Required. The client-assigned sink identifier, unique within
@@ -279,6 +282,7 @@ class LogSink(proto.Message):
         bigquery_options (google.cloud.logging_v2.types.BigQueryOptions):
             Optional. Options that affect sinks exporting
             data to BigQuery.
+            This field is a member of `oneof`_ ``options``.
         create_time (google.protobuf.timestamp_pb2.Timestamp):
             Output only. The creation timestamp of the
             sink.

tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py

@@ -501,10 +501,13 @@ class GcsSource(proto.Message):
 class InputConfig(proto.Message):
     r"""The input content
 
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         gcs_source (google.cloud.redis_v1.types.GcsSource):
             Google Cloud Storage location where input
             content is located.
+            This field is a member of `oneof`_ ``source``.
     """
 
     gcs_source = proto.Field(
@@ -558,10 +561,13 @@ class GcsDestination(proto.Message):
 class OutputConfig(proto.Message):
     r"""The output content
 
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         gcs_destination (google.cloud.redis_v1.types.GcsDestination):
             Google Cloud Storage destination for output
             content.
+            This field is a member of `oneof`_ ``destination``.
     """
 
     gcs_destination = proto.Field(