docs: clarified some LRO types (#387)

- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 394490143

Source-Link: googleapis/googleapis@e3c419f

Source-Link: googleapis/googleapis-gen@c73fc0d

Author: gcf-owl-bot[bot]

packages/google-cloud-dialogflow/google/cloud/dialogflow_v2/services/agents/async_client.py

@@ -482,6 +482,16 @@ async def train_agent(
     ) -> operation_async.AsyncOperation:
         r"""Trains the specified agent.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
         Note: You should always train an agent prior to sending it
         queries. See the `training
         documentation <https://cloud.google.com/dialogflow/es/docs/training>`__.
@@ -578,6 +588,16 @@ async def export_agent(
     ) -> operation_async.AsyncOperation:
         r"""Exports the specified agent to a ZIP file.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``:
+           [ExportAgentResponse][google.cloud.dialogflow.v2.ExportAgentResponse]
+
         Args:
             request (:class:`google.cloud.dialogflow_v2.types.ExportAgentRequest`):
                 The request object. The request message for
@@ -671,9 +691,18 @@ async def import_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when importing is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when importing is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training
@@ -758,9 +787,18 @@ async def restore_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when restoring is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when restoring is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training

packages/google-cloud-dialogflow/google/cloud/dialogflow_v2/services/agents/client.py

@@ -674,6 +674,16 @@ def train_agent(
     ) -> operation.Operation:
         r"""Trains the specified agent.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
         Note: You should always train an agent prior to sending it
         queries. See the `training
         documentation <https://cloud.google.com/dialogflow/es/docs/training>`__.
@@ -770,6 +780,16 @@ def export_agent(
     ) -> operation.Operation:
         r"""Exports the specified agent to a ZIP file.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``:
+           [ExportAgentResponse][google.cloud.dialogflow.v2.ExportAgentResponse]
+
         Args:
             request (google.cloud.dialogflow_v2.types.ExportAgentRequest):
                 The request object. The request message for
@@ -863,9 +883,18 @@ def import_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when importing is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when importing is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training
@@ -951,9 +980,18 @@ def restore_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when restoring is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when restoring is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training

packages/google-cloud-dialogflow/google/cloud/dialogflow_v2/services/agents/transports/grpc.py

@@ -361,6 +361,16 @@ def train_agent(
 
         Trains the specified agent.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
         Note: You should always train an agent prior to sending it
         queries. See the `training
         documentation <https://cloud.google.com/dialogflow/es/docs/training>`__.
@@ -391,6 +401,16 @@ def export_agent(
 
         Exports the specified agent to a ZIP file.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``:
+           [ExportAgentResponse][google.cloud.dialogflow.v2.ExportAgentResponse]
+
         Returns:
             Callable[[~.ExportAgentRequest],
                     ~.Operation]:
@@ -428,9 +448,18 @@ def import_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when importing is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when importing is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training
@@ -471,9 +500,18 @@ def restore_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when restoring is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when restoring is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training

packages/google-cloud-dialogflow/google/cloud/dialogflow_v2/services/agents/transports/grpc_asyncio.py

@@ -370,6 +370,16 @@ def train_agent(
 
         Trains the specified agent.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
         Note: You should always train an agent prior to sending it
         queries. See the `training
         documentation <https://cloud.google.com/dialogflow/es/docs/training>`__.
@@ -400,6 +410,16 @@ def export_agent(
 
         Exports the specified agent to a ZIP file.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``:
+           [ExportAgentResponse][google.cloud.dialogflow.v2.ExportAgentResponse]
+
         Returns:
             Callable[[~.ExportAgentRequest],
                     Awaitable[~.Operation]]:
@@ -437,9 +457,18 @@ def import_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when importing is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when importing is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training
@@ -480,9 +509,18 @@ def restore_agent(
         and wait for the operation it returns in order to train
         explicitly.
 
-        An operation which tracks when restoring is complete. It only
-        tracks when the draft agent is updated not when it is done
-        training.
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/es/docs/how/long-running-operations>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``: An empty `Struct
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`__
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
+
+        The operation only tracks when restoring is complete, not when
+        it is done training.
 
         Note: You should always train an agent prior to sending it
         queries. See the `training

packages/google-cloud-dialogflow/google/cloud/dialogflow_v2/services/documents/async_client.py

@@ -334,9 +334,14 @@ async def create_document(
     ) -> operation_async.AsyncOperation:
         r"""Creates a new document.
 
-        Operation <response:
-        [Document][google.cloud.dialogflow.v2.Document], metadata:
-        [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]>
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``:
+           [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]
+        -  ``response``: [Document][google.cloud.dialogflow.v2.Document]
 
         Args:
             request (:class:`google.cloud.dialogflow_v2.types.CreateDocumentRequest`):
@@ -436,9 +441,15 @@ async def delete_document(
     ) -> operation_async.AsyncOperation:
         r"""Deletes the specified document.
 
-        Operation <response:
-        [google.protobuf.Empty][google.protobuf.Empty], metadata:
-        [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]>
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``:
+           [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]
+        -  ``response``: An `Empty
+           message <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty>`__
 
         Args:
             request (:class:`google.cloud.dialogflow_v2.types.DeleteDocumentRequest`):
@@ -533,9 +544,14 @@ async def update_document(
     ) -> operation_async.AsyncOperation:
         r"""Updates the specified document.
 
-        Operation <response:
-        [Document][google.cloud.dialogflow.v2.Document], metadata:
-        [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]>
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``:
+           [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]
+        -  ``response``: [Document][google.cloud.dialogflow.v2.Document]
 
         Args:
             request (:class:`google.cloud.dialogflow_v2.types.UpdateDocumentRequest`):
@@ -642,13 +658,18 @@ async def reload_document(
         document has not changed, there still may be side effects
         because of internal implementation changes.
 
+        This method is a `long-running
+        operation <https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation>`__.
+        The returned ``Operation`` type has the following
+        method-specific fields:
+
+        -  ``metadata``:
+           [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]
+        -  ``response``: [Document][google.cloud.dialogflow.v2.Document]
+
         Note: The ``projects.agent.knowledgeBases.documents`` resource
         is deprecated; only use ``projects.knowledgeBases.documents``.
 
-        Operation <response:
-        [Document][google.cloud.dialogflow.v2.Document], metadata:
-        [KnowledgeOperationMetadata][google.cloud.dialogflow.v2.KnowledgeOperationMetadata]>
-
         Args:
             request (:class:`google.cloud.dialogflow_v2.types.ReloadDocumentRequest`):
                 The request object. Request message for