[Storage] Fix documentation for start_copy_from_url (Azure#24034)

Author: jalauzon-msft

sdk/storage/azure-storage-blob/azure/storage/blob/_blob_client.py

@@ -1946,11 +1946,14 @@ def _start_copy_from_url_options(self, source_url, metadata=None, incremental_co
     @distributed_trace
     def start_copy_from_url(self, source_url, metadata=None, incremental_copy=False, **kwargs):
         # type: (str, Optional[Dict[str, str]], bool, **Any) -> Dict[str, Union[str, datetime]]
-        """Copies a blob asynchronously.
-
-        This operation returns a copy operation
-        object that can be used to wait on the completion of the operation,
-        as well as check status or abort the copy operation.
+        """Copies a blob from the given URL.
+
+        This operation returns a dictionary containing `copy_status` and `copy_id`,
+        which can be used to check the status of or abort the copy operation.
+        `copy_status` will be 'success' if the copy completed synchronously or
+        'pending' if the copy has been started asynchronously. For asynchronous copies,
+        the status can be checked by polling the :func:`get_blob_properties` method and
+        checking the copy status. Set `requires_sync` to True to force the copy to be synchronous.
         The Blob service copies blobs on a best-effort basis.
 
         The source blob for a copy operation may be a block blob, an append blob,
@@ -1973,10 +1976,6 @@ def start_copy_from_url(self, source_url, metadata=None, incremental_copy=False,
         end of the copy operation, the destination blob will have the same committed
         block count as the source.
 
-        For all blob types, you can call status() on the returned polling object
-        to check the status of the copy operation, or wait() to block until the
-        operation is complete. The final blob will be committed when the copy completes.
-
         :param str source_url:
             A URL of up to 2 KB in length that specifies a file or blob.
             The value should be URL-encoded as it would appear in a request URI.

sdk/storage/azure-storage-blob/azure/storage/blob/aio/_blob_client_async.py

@@ -1126,12 +1126,15 @@ async def create_snapshot(self, metadata=None, **kwargs):
 
     @distributed_trace_async
     async def start_copy_from_url(self, source_url, metadata=None, incremental_copy=False, **kwargs):
-        # type: (str, Optional[Dict[str, str]], bool, Any) -> Any
-        """Copies a blob asynchronously.
-
-        This operation returns a copy operation
-        object that can be used to wait on the completion of the operation,
-        as well as check status or abort the copy operation.
+        # type: (str, Optional[Dict[str, str]], bool, Any) -> Dict[str, Union[str, datetime]]
+        """Copies a blob from the given URL.
+
+        This operation returns a dictionary containing `copy_status` and `copy_id`,
+        which can be used to check the status of or abort the copy operation.
+        `copy_status` will be 'success' if the copy completed synchronously or
+        'pending' if the copy has been started asynchronously. For asynchronous copies,
+        the status can be checked by polling the :func:`get_blob_properties` method and
+        checking the copy status. Set `requires_sync` to True to force the copy to be synchronous.
         The Blob service copies blobs on a best-effort basis.
 
         The source blob for a copy operation may be a block blob, an append blob,
@@ -1154,10 +1157,6 @@ async def start_copy_from_url(self, source_url, metadata=None, incremental_copy=
         end of the copy operation, the destination blob will have the same committed
         block count as the source.
 
-        For all blob types, you can call status() on the returned polling object
-        to check the status of the copy operation, or wait() to block until the
-        operation is complete. The final blob will be committed when the copy completes.
-
         :param str source_url:
             A URL of up to 2 KB in length that specifies a file or blob.
             The value should be URL-encoded as it would appear in a request URI.