refactor(storage): deprecate preserve_acl arg in copy_blob() method (#…

…104)

* refactor(storage): deprecate preserve_acl arg in copy_blob() method

* Revert "refactor(storage): deprecate preserve_acl arg in copy_blob() method"

This reverts commit edd0137.

* add deprecation warning into docs, provide a snippet of how to copy ACL

Co-authored-by: Frank Natividad <frankyn@users.noreply.github.com>

google/cloud/storage/bucket.py

@@ -1272,7 +1272,8 @@ def copy_blob(
                        to the ``client`` stored on the current bucket.
 
         :type preserve_acl: bool
-        :param preserve_acl: (Optional) Copies ACL from old blob to new blob.
+        :param preserve_acl: DEPRECATED. This argument is not functional!
+                             (Optional) Copies ACL from old blob to new blob.
                              Default: True.
 
         :type source_generation: long
@@ -1288,6 +1289,20 @@ def copy_blob(
 
         :rtype: :class:`google.cloud.storage.blob.Blob`
         :returns: The new Blob.
+
+        Example:
+            Copy a blob including ACL.
+
+            >>> from google.cloud import storage
+
+            >>> client = storage.Client(project="project")
+
+            >>> bucket = client.bucket("bucket")
+            >>> dst_bucket = client.bucket("destination-bucket")
+
+            >>> blob = bucket.blob("file.ext")
+            >>> new_blob = bucket.copy_blob(blob, dst_bucket)
+            >>> new_blob.acl.save(blob.acl)
         """
         client = self._require_client(client)
         query_params = {}