docs: Add documentation for enums (#492)

* chore: fix proto formatting PiperOrigin-RevId: 503230949 Source-Link: googleapis/googleapis@55dd4d7 Source-Link: googleapis/googleapis-gen@588ff38 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNTg4ZmYzOGNmM2EyZGQyMjY0ZGE1YjAzMGQxZjcyZTU2YzdmZmM2NiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Jan 20, 2023 · dc4f8e2 · dc4f8e2
1 parent ea24ddb
commit dc4f8e2
Show file tree

Hide file tree

Showing 64 changed files with 1,106 additions and 86 deletions.
diff --git a/google/cloud/dialogflowcx_v3/services/agents/client.py b/google/cloud/dialogflowcx_v3/services/agents/client.py
@@ -1566,7 +1566,7 @@ def sample_get_agent_validation_result():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "AgentsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/changelogs/client.py b/google/cloud/dialogflowcx_v3/services/changelogs/client.py
@@ -662,7 +662,7 @@ def sample_get_changelog():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "ChangelogsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/deployments/client.py b/google/cloud/dialogflowcx_v3/services/deployments/client.py
@@ -753,7 +753,7 @@ def sample_get_deployment():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "DeploymentsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/entity_types/client.py b/google/cloud/dialogflowcx_v3/services/entity_types/client.py
@@ -1094,7 +1094,7 @@ def sample_delete_entity_type():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "EntityTypesClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/environments/client.py b/google/cloud/dialogflowcx_v3/services/environments/client.py
@@ -1695,7 +1695,7 @@ def sample_deploy_flow():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "EnvironmentsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/experiments/client.py b/google/cloud/dialogflowcx_v3/services/experiments/client.py
@@ -1239,7 +1239,7 @@ def sample_stop_experiment():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "ExperimentsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/flows/client.py b/google/cloud/dialogflowcx_v3/services/flows/client.py
@@ -1730,7 +1730,7 @@ def sample_export_flow():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "FlowsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/intents/client.py b/google/cloud/dialogflowcx_v3/services/intents/client.py
@@ -1035,7 +1035,7 @@ def sample_delete_intent():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "IntentsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/pages/client.py b/google/cloud/dialogflowcx_v3/services/pages/client.py
@@ -1178,7 +1178,7 @@ def sample_delete_page():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "PagesClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/security_settings_service/client.py b/google/cloud/dialogflowcx_v3/services/security_settings_service/client.py
@@ -1069,7 +1069,7 @@ def sample_delete_security_settings():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "SecuritySettingsServiceClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/session_entity_types/client.py b/google/cloud/dialogflowcx_v3/services/session_entity_types/client.py
@@ -1091,7 +1091,7 @@ def sample_delete_session_entity_type():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "SessionEntityTypesClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/sessions/client.py b/google/cloud/dialogflowcx_v3/services/sessions/client.py
@@ -1068,7 +1068,7 @@ def sample_fulfill_intent():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "SessionsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/test_cases/client.py b/google/cloud/dialogflowcx_v3/services/test_cases/client.py
@@ -1934,7 +1934,7 @@ def sample_get_test_case_result():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "TestCasesClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/transition_route_groups/client.py b/google/cloud/dialogflowcx_v3/services/transition_route_groups/client.py
@@ -1160,7 +1160,7 @@ def sample_delete_transition_route_group():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "TransitionRouteGroupsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/versions/client.py b/google/cloud/dialogflowcx_v3/services/versions/client.py
@@ -1271,7 +1271,7 @@ def sample_compare_versions():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "VersionsClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/services/webhooks/client.py b/google/cloud/dialogflowcx_v3/services/webhooks/client.py
@@ -1026,7 +1026,7 @@ def sample_delete_webhook():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "WebhooksClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/dialogflowcx_v3/types/agent.py b/google/cloud/dialogflowcx_v3/types/agent.py
@@ -370,7 +370,14 @@ class ExportAgentRequest(proto.Message):
     """
 
     class DataFormat(proto.Enum):
-        r"""Data format of the exported agent."""
+        r"""Data format of the exported agent.
+
+        Values:
+            DATA_FORMAT_UNSPECIFIED (0):
+                Unspecified format.
+            BLOB (1):
+                Agent content will be exported as raw bytes.
+        """
         DATA_FORMAT_UNSPECIFIED = 0
         BLOB = 1
 
@@ -466,7 +473,20 @@ class RestoreAgentRequest(proto.Message):
     """
 
     class RestoreOption(proto.Enum):
-        r"""Restore option."""
+        r"""Restore option.
+
+        Values:
+            RESTORE_OPTION_UNSPECIFIED (0):
+                Unspecified. Treated as KEEP.
+            KEEP (1):
+                Always respect the settings from the exported
+                agent file. It may cause a restoration failure
+                if some settings (e.g. model type) are not
+                supported in the target agent.
+            FALLBACK (2):
+                Fallback to default settings if some settings
+                are not supported in the target agent.
+        """
         RESTORE_OPTION_UNSPECIFIED = 0
         KEEP = 1
         FALLBACK = 2

diff --git a/google/cloud/dialogflowcx_v3/types/audio_config.py b/google/cloud/dialogflowcx_v3/types/audio_config.py
@@ -41,6 +41,50 @@ class AudioEncoding(proto.Enum):
     request. Refer to the `Cloud Speech API
     documentation <https://cloud.google.com/speech-to-text/docs/basics>`__
     for more details.
+
+    Values:
+        AUDIO_ENCODING_UNSPECIFIED (0):
+            Not specified.
+        AUDIO_ENCODING_LINEAR_16 (1):
+            Uncompressed 16-bit signed little-endian
+            samples (Linear PCM).
+        AUDIO_ENCODING_FLAC (2):
+            ```FLAC`` <https://xiph.org/flac/documentation.html>`__
+            (Free Lossless Audio Codec) is the recommended encoding
+            because it is lossless (therefore recognition is not
+            compromised) and requires only about half the bandwidth of
+            ``LINEAR16``. ``FLAC`` stream encoding supports 16-bit and
+            24-bit samples, however, not all fields in ``STREAMINFO``
+            are supported.
+        AUDIO_ENCODING_MULAW (3):
+            8-bit samples that compand 14-bit audio
+            samples using G.711 PCMU/mu-law.
+        AUDIO_ENCODING_AMR (4):
+            Adaptive Multi-Rate Narrowband codec. ``sample_rate_hertz``
+            must be 8000.
+        AUDIO_ENCODING_AMR_WB (5):
+            Adaptive Multi-Rate Wideband codec. ``sample_rate_hertz``
+            must be 16000.
+        AUDIO_ENCODING_OGG_OPUS (6):
+            Opus encoded audio frames in Ogg container
+            (`OggOpus <https://wiki.xiph.org/OggOpus>`__).
+            ``sample_rate_hertz`` must be 16000.
+        AUDIO_ENCODING_SPEEX_WITH_HEADER_BYTE (7):
+            Although the use of lossy encodings is not recommended, if a
+            very low bitrate encoding is required, ``OGG_OPUS`` is
+            highly preferred over Speex encoding. The
+            `Speex <https://speex.org/>`__ encoding supported by
+            Dialogflow API has a header byte in each block, as in MIME
+            type ``audio/x-speex-with-header-byte``. It is a variant of
+            the RTP Speex encoding defined in `RFC
+            5574 <https://tools.ietf.org/html/rfc5574>`__. The stream is
+            a sequence of blocks, one block per RTP packet. Each block
+            starts with a byte containing the length of the block, in
+            bytes, followed by one or more frames of Speex data, padded
+            to an integral number of bytes (octets) as specified in RFC
+            5574. In other words, each RTP header is replaced with a
+            single byte containing the block length. Only Speex wideband
+            is supported. ``sample_rate_hertz`` must be 16000.
     """
     AUDIO_ENCODING_UNSPECIFIED = 0
     AUDIO_ENCODING_LINEAR_16 = 1
@@ -62,6 +106,40 @@ class SpeechModelVariant(proto.Enum):
     "phone_call" model has both a standard and an enhanced variant. When
     you use an enhanced model, you will generally receive higher quality
     results than for a standard model.
+
+    Values:
+        SPEECH_MODEL_VARIANT_UNSPECIFIED (0):
+            No model variant specified. In this case Dialogflow defaults
+            to USE_BEST_AVAILABLE.
+        USE_BEST_AVAILABLE (1):
+            Use the best available variant of the [Speech
+            model][InputAudioConfig.model] that the caller is eligible
+            for.
+
+            Please see the `Dialogflow
+            docs <https://cloud.google.com/dialogflow/docs/data-logging>`__
+            for how to make your project eligible for enhanced models.
+        USE_STANDARD (2):
+            Use standard model variant even if an enhanced model is
+            available. See the `Cloud Speech
+            documentation <https://cloud.google.com/speech-to-text/docs/enhanced-models>`__
+            for details about enhanced models.
+        USE_ENHANCED (3):
+            Use an enhanced model variant:
+
+            -  If an enhanced variant does not exist for the given
+               [model][google.cloud.dialogflow.cx.v3.InputAudioConfig.model]
+               and request language, Dialogflow falls back to the
+               standard variant.
+
+               The `Cloud Speech
+               documentation <https://cloud.google.com/speech-to-text/docs/enhanced-models>`__
+               describes which models have enhanced variants.
+
+            -  If the API caller isn't eligible for enhanced models,
+               Dialogflow returns an error. Please see the `Dialogflow
+               docs <https://cloud.google.com/dialogflow/docs/data-logging>`__
+               for how to make your project eligible.
     """
     SPEECH_MODEL_VARIANT_UNSPECIFIED = 0
     USE_BEST_AVAILABLE = 1
@@ -72,6 +150,18 @@ class SpeechModelVariant(proto.Enum):
 class SsmlVoiceGender(proto.Enum):
     r"""Gender of the voice as described in `SSML voice
     element <https://www.w3.org/TR/speech-synthesis11/#edef_voice>`__.
+
+    Values:
+        SSML_VOICE_GENDER_UNSPECIFIED (0):
+            An unspecified gender, which means that the
+            client doesn't care which gender the selected
+            voice will have.
+        SSML_VOICE_GENDER_MALE (1):
+            A male voice.
+        SSML_VOICE_GENDER_FEMALE (2):
+            A female voice.
+        SSML_VOICE_GENDER_NEUTRAL (3):
+            A gender-neutral voice.
     """
     SSML_VOICE_GENDER_UNSPECIFIED = 0
     SSML_VOICE_GENDER_MALE = 1
@@ -80,7 +170,30 @@ class SsmlVoiceGender(proto.Enum):
 
 
 class OutputAudioEncoding(proto.Enum):
-    r"""Audio encoding of the output audio format in Text-To-Speech."""
+    r"""Audio encoding of the output audio format in Text-To-Speech.
+
+    Values:
+        OUTPUT_AUDIO_ENCODING_UNSPECIFIED (0):
+            Not specified.
+        OUTPUT_AUDIO_ENCODING_LINEAR_16 (1):
+            Uncompressed 16-bit signed little-endian
+            samples (Linear PCM). Audio content returned as
+            LINEAR16 also contains a WAV header.
+        OUTPUT_AUDIO_ENCODING_MP3 (2):
+            MP3 audio at 32kbps.
+        OUTPUT_AUDIO_ENCODING_MP3_64_KBPS (4):
+            MP3 audio at 64kbps.
+        OUTPUT_AUDIO_ENCODING_OGG_OPUS (3):
+            Opus encoded audio wrapped in an ogg
+            container. The result will be a file which can
+            be played natively on Android, and in browsers
+            (at least Chrome and Firefox). The quality of
+            the encoding is considerably higher than MP3
+            while using approximately the same bitrate.
+        OUTPUT_AUDIO_ENCODING_MULAW (5):
+            8-bit samples that compand 14-bit audio
+            samples using G.711 PCMU/mu-law.
+    """
     OUTPUT_AUDIO_ENCODING_UNSPECIFIED = 0
     OUTPUT_AUDIO_ENCODING_LINEAR_16 = 1
     OUTPUT_AUDIO_ENCODING_MP3 = 2

diff --git a/google/cloud/dialogflowcx_v3/types/deployment.py b/google/cloud/dialogflowcx_v3/types/deployment.py
@@ -61,7 +61,18 @@ class Deployment(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""The state of the deployment."""
+        r"""The state of the deployment.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                State unspecified.
+            RUNNING (1):
+                The deployment is running.
+            SUCCEEDED (2):
+                The deployment succeeded.
+            FAILED (3):
+                The deployment failed.
+        """
         STATE_UNSPECIFIED = 0
         RUNNING = 1
         SUCCEEDED = 2

diff --git a/google/cloud/dialogflowcx_v3/types/entity_type.py b/google/cloud/dialogflowcx_v3/types/entity_type.py
@@ -103,7 +103,24 @@ class EntityType(proto.Message):
     """
 
     class Kind(proto.Enum):
-        r"""Represents kinds of entities."""
+        r"""Represents kinds of entities.
+
+        Values:
+            KIND_UNSPECIFIED (0):
+                Not specified. This value should be never
+                used.
+            KIND_MAP (1):
+                Map entity types allow mapping of a group of
+                synonyms to a canonical value.
+            KIND_LIST (2):
+                List entity types contain a set of entries
+                that do not map to canonical values. However,
+                list entity types can contain references to
+                other entity types (with or without aliases).
+            KIND_REGEXP (3):
+                Regexp entity types allow to specify regular
+                expressions in entries values.
+        """
         KIND_UNSPECIFIED = 0
         KIND_MAP = 1
         KIND_LIST = 2
@@ -114,6 +131,13 @@ class AutoExpansionMode(proto.Enum):
         expansion allows an agent to recognize values that have not been
         explicitly listed in the entity (for example, new kinds of
         shopping list items).
+
+        Values:
+            AUTO_EXPANSION_MODE_UNSPECIFIED (0):
+                Auto expansion disabled for the entity.
+            AUTO_EXPANSION_MODE_DEFAULT (1):
+                Allows an agent to recognize values that have
+                not been explicitly listed in the entity.
         """
         AUTO_EXPANSION_MODE_UNSPECIFIED = 0
         AUTO_EXPANSION_MODE_DEFAULT = 1

diff --git a/google/cloud/dialogflowcx_v3/types/environment.py b/google/cloud/dialogflowcx_v3/types/environment.py
@@ -418,6 +418,14 @@ class ContinuousTestResult(proto.Message):
     class AggregatedTestResult(proto.Enum):
         r"""The overall result for a continuous test run in an agent
         environment.
+
+        Values:
+            AGGREGATED_TEST_RESULT_UNSPECIFIED (0):
+                Not specified. Should never be used.
+            PASSED (1):
+                All the tests passed.
+            FAILED (2):
+                At least one test did not pass.
         """
         AGGREGATED_TEST_RESULT_UNSPECIFIED = 0
         PASSED = 1