Repository: googleapis/python-storage

Issue:
Move boilerplate docs for 'if_generation_match' et al. out of method docstrings
See also #455.

There are a ton of API-invoking methods which take `if_generation_match`, `if_generation_not_match`, etc. and have docstring entries for each of them which are both too verbose and too terse: they don't include / reference examples, and they are wordy. y preference, they would point instead to a narrative page (built from e.g. `docs/conditional_arguments.rst`) which would include comprehensive examples for them.

Discussion:
tseaver: Blocked pending merges of PR #447, PR #454.
tseaver: @cojenco, @andrewsg ready for review.
tseaver: @frankyn, @tritone, @andrewsg, @cojenco PTAL.
cojenco: Thanks for the ping, @tseaver . Taking a look now.
dandhlee: `docfx` and docs-presubmit will fail, sorry about that! If if's just those two and you can move the PR along then please do so, otherwise you'll have to wait until I resolve it with https://github.com/googleapis/sphinx-docfx-yaml/pull/48.
dandhlee: Everything is fixed! Sorry to make you wait 😅 

Patch:
diff --git a/docs/generation_metageneration.rst b/docs/generation_metageneration.rst
new file mode 100644
index 0000000..287e657
--- /dev/null
+++ b/docs/generation_metageneration.rst
@@ -0,0 +1,127 @@
+Conditional Requests Via Generation / Metageneration Preconditions
+==================================================================
+
+Preconditions tell Cloud Storage to only perform a request if the
+:ref:`generation <concept-generation>` or
+:ref:`metageneration <concept-metageneration>` number of the affected object
+meets your precondition criteria. These checks of the generation and
+metageneration numbers ensure that the object is in the expected state,
+allowing you to perform safe read-modify-write updates and conditional
+operations on objects
+
+Concepts
+--------
+
+.. _concept-metageneration:
+
+Metageneration
+::::::::::::::
+
+When you create a :class:`~google.cloud.storage.bucket.Bucket`,
+its :attr:`~google.cloud.storage.bucket.Bucket.metageneration` is initialized
+to ``1``, representing the initial version of the bucket's metadata.
+
+When you first upload a
+:class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs),
+its :attr:`~google.cloud.storage.blob.Blob.metageneration` is likewise
+initialized to ``1``.  representing the initial version of the blob's metadata.
+
+The ``metageneration`` attribute is set by the GCS back-end, and is read-only
+in the client library.
+
+Each time you patch or update the bucket's / blob's metadata, its
+``metageneration`` is incremented.
+
+
+.. _concept-generation:
+
+Generation
+::::::::::
+
+Each time you upload a new version of a file to a
+:class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs),
+the Blob's :attr:`~google.cloud.storage.blob.generation` is changed, and its
+:attr:`~google.cloud.storage.blob.metageneration` is reset to ``1`` (the first
+metadata version for that generation of the blob).
+
+The ``generation`` attribute is set by the GCS back-end, and is read-only
+in the client library.
+
+See also
+::::::::
+
+- `Storage API Generation Precondition docs`_
+
+.. _Storage API Generation Precondition docs:
+   https://cloud.google.com/storage/docs/generations-preconditions
+
+
+Conditional Parameters
+----------------------
+
+.. _using-if-generation-match:
+
+Using ``if_generation_match``
+:::::::::::::::::::::::::::::
+
+Passing the ``if_generation_match`` parameter to a method which retrieves a
+blob resource (e.g.,
+:meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies
+the blob (e.g.,
+:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`)
+makes the operation conditional on whether the blob's current ``generation``
+matches the given value.
+
+As a special case, passing ``0`` as the value for``if_generation_match``
+makes the operation succeed only if there are no live versions of the blob.
+
+
+.. _using-if-generation-not-match:
+
+Using ``if_generation_not_match``
+:::::::::::::::::::::::::::::::::
+
+Passing the ``if_generation_not_match`` parameter to a method which retrieves
+a blob resource (e.g.,
+:meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies
+the blob (e.g.,
+:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`)
+makes the operation conditional on whether the blob's current ``generation``
+does **not** match the given value.
+
+If no live version of the blob exists, the precondition fails.
+
+As a special case, passing ``0`` as the value for ``if_generation_not_match``
+makes the operation succeed only if there **is** a live version of the blob.
+
+
+.. _using-if-metageneration-match:
+
+Using ``if_metageneration_match``
+:::::::::::::::::::::::::::::::::
+
+Passing the ``if_metageneration_match`` parameter to a method which retrieves
+a blob or bucket resource
+(e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`,
+:meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`)
+or modifies the blob or bucket (e.g.,
+:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`
+:meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`)
+makes the operation conditional on whether the resource's current
+``metageneration`` matches the given value.
+
+
+.. _using-if-metageneration-not-match:
+
+Using ``if_metageneration_not_match``
+:::::::::::::::::::::::::::::::::::::
+
+Passing the ``if_metageneration_not_match`` parameter to a method which
+retrieves a blob or bucket resource
+(e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`,
+:meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`)
+or modifies the blob or bucket (e.g.,
+:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`
+:meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`)
+makes the operation conditional on whether the resource's current
+``metageneration`` does **not** match the given value.
diff --git a/docs/index.rst b/docs/index.rst
index 051bac8..9ece797 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,6 +22,7 @@ API Reference
   hmac_key
   notification
   retry_timeout
+  generation_metageneration
 
 Changelog
 ---------
diff --git a/google/cloud/storage/_helpers.py b/google/cloud/storage/_helpers.py
index 0467103..ff5767d 100644
--- a/google/cloud/storage/_helpers.py
+++ b/google/cloud/storage/_helpers.py
@@ -147,11 +147,11 @@ class _PropertyMixin(object):
         self,
         client=None,
         projection="noAcl",
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY,
     ):
         """Reload properties from Cloud Storage.
@@ -168,31 +168,26 @@ class _PropertyMixin(object):
                            Defaults to ``'noAcl'``. Specifies the set of
                            properties to return.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -251,11 +246,11 @@ class _PropertyMixin(object):
     def patch(
         self,
         client=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
     ):
         """Sends all changed properties in a PATCH request.
@@ -269,31 +264,26 @@ class _PropertyMixin(object):
         :param client: the client to use. If not passed, falls back to the
                        ``client`` stored on the current object.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -327,11 +317,11 @@ class _PropertyMixin(object):
     def update(
         self,
         client=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
     ):
         """Sends all properties in a PUT request.
@@ -345,31 +335,26 @@ class _PropertyMixin(object):
         :param client: the client to use. If not passed, falls back to the
                        ``client`` stored on the current object.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py
index c22e669..60178aa 100644
--- a/google/cloud/storage/blob.py
+++ b/google/cloud/storage/blob.py
@@ -116,6 +116,25 @@ _CHUNKED_DOWNLOAD_CHECKSUM_MESSAGE = (
     "A checksum of type `{}` was requested, but checksumming is not available "
     "for downloads when chunk_size is set."
 )
+_COMPOSE_IF_GENERATION_LIST_DEPRECATED = (
+    "'if_generation_match: type list' is deprecated and supported for "
+    "backwards-compatability reasons only.  Use 'if_source_generation_match' "
+    "instead' to match source objects' generations.",
+)
+_COMPOSE_IF_GENERATION_LIST_AND_IF_SOURCE_GENERATION_ERROR = (
+    "Use 'if_generation_match' to match the generation of the destination "
+    "object by passing in a generation number, instead of a list. "
+    "Use 'if_source_generation_match' to match source objects generations."
+)
+_COMPOSE_IF_METAGENERATION_LIST_DEPRECATED = (
+    "'if_metageneration_match: type list' is deprecated and supported for "
+    "backwards-compatability reasons only. Note that the metageneration to "
+    "be matched is that of the destination blob. Please pass in a single "
+    "value (type long).",
+)
+_COMPOSE_IF_SOURCE_GENERATION_MISMATCH_ERROR = (
+    "'if_source_generation_match' length must be the same as 'sources' length"
+)
 
 
 _DEFAULT_CHUNKSIZE = 104857600  # 1024 * 1024 B * 100 = 100 MB
@@ -616,11 +635,11 @@ class Blob(_PropertyMixin):
     def exists(
         self,
         client=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY,
     ):
         """Determines whether or not this blob exists.
@@ -633,33 +652,26 @@ class Blob(_PropertyMixin):
             (Optional) The client to use.  If not passed, falls back to the
             ``client`` stored on the blob's bucket.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -701,11 +713,11 @@ class Blob(_PropertyMixin):
     def delete(
         self,
         client=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
     ):
         """Deletes a blob from Cloud Storage.
@@ -718,33 +730,26 @@ class Blob(_PropertyMixin):
             (Optional) The client to use. If not passed, falls back to the
             ``client`` stored on the blob's bucket.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -801,25 +806,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
+        :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :rtype: str
         :returns: The download URL for the current blob.
@@ -1056,25 +1055,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
+        :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1173,25 +1166,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
+        :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1299,25 +1286,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
+        :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1418,25 +1399,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
+        :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1530,26 +1505,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1746,26 +1714,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -1937,26 +1898,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -2127,26 +2081,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -2268,26 +2215,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -2473,26 +2413,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -2636,26 +2569,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -2777,26 +2703,19 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation matches the given value.  Setting to 0 makes the
-            operation succeed only if there are no live versions of the blob.
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current generation does not match the given value. If no live blob
-            exists, the precondition fails.  Setting to 0 makes the operation
-            succeed only if there is a live version of the blob.
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration matches the given value.
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Make the operation conditional on whether the blob's
-            current metageneration does not match the given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
 
         :type timeout: float or tuple
         :param timeout:
@@ -3226,10 +3145,13 @@ class Blob(_PropertyMixin):
             Setting to 0 makes the operation succeed only if there are no live
             versions of the object.
 
-            Note: In a previous version, this argument worked identically to the
-            ``if_source_generation_match`` argument. For backwards-compatibility reasons,
-            if a list is passed in, this argument will behave like ``if_source_generation_match``
-            and also issue a DeprecationWarning.
+            .. note::
+
+              In a previous version, this argument worked identically to the
+              ``if_source_generation_match`` argument. For
+              backwards-compatibility reasons, if a list is passed in,
+              this argument will behave like ``if_source_generation_match``
+              and also issue a DeprecationWarning.
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
@@ -3237,13 +3159,14 @@ class Blob(_PropertyMixin):
             destination object's current metageneration matches the given
             value.
 
-            If a list of long is passed in, no match operation will be performed.
-            (Deprecated: type(list of long) is supported for backwards-compatability reasons only.)
+            If a list of long is passed in, no match operation will be
+            performed.  (Deprecated: type(list of long) is supported for
+            backwards-compatability reasons only.)
 
         :type if_source_generation_match: list of long
         :param if_source_generation_match:
-            (Optional) Makes the operation conditional on whether the current generation
-            of each source blob matches the corresponding generation.
+            (Optional) Makes the operation conditional on whether the current
+            generation of each source blob matches the corresponding generation.
             The list must match ``sources`` item-to-item.
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
@@ -3270,27 +3193,22 @@ class Blob(_PropertyMixin):
 
         if isinstance(if_generation_match, list):
             warnings.warn(
-                "if_generation_match: type list is deprecated and supported for backwards-compatability reasons only."
-                "Use if_source_generation_match instead to match source objects generations.",
+                _COMPOSE_IF_GENERATION_LIST_DEPRECATED,
                 DeprecationWarning,
                 stacklevel=2,
             )
 
             if if_source_generation_match is not None:
                 raise ValueError(
-                    "Use if_generation_match to match the generation of the destination object by passing in a generation number, instead of a list."
-                    "Use if_source_generation_match to match source objects generations."
+                    _COMPOSE_IF_GENERATION_LIST_AND_IF_SOURCE_GENERATION_ERROR
                 )
 
-            # if_generation_match: type list is deprecated. Instead use if_source_generation_match.
             if_source_generation_match = if_generation_match
             if_generation_match = None
 
         if isinstance(if_metageneration_match, list):
             warnings.warn(
-                "if_metageneration_match: type list is deprecated and supported for backwards-compatability reasons only."
-                "Note that the metageneration to be matched is that of the destination blob."
-                "Please pass in a single value (type long).",
+                _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED,
                 DeprecationWarning,
                 stacklevel=2,
             )
@@ -3300,9 +3218,7 @@ class Blob(_PropertyMixin):
         if if_source_generation_match is None:
             if_source_generation_match = [None] * sources_len
         if len(if_source_generation_match) != sources_len:
-            raise ValueError(
-                "'if_source_generation_match' length must be the same as 'sources' length"
-            )
+            raise ValueError(_COMPOSE_IF_SOURCE_GENERATION_MISMATCH_ERROR)
 
         source_objects = []
         for source, source_generation in zip(sources, if_source_generation_match):
@@ -3346,7 +3262,6 @@ class Blob(_PropertyMixin):
         source,
         token=None,
         client=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
@@ -3355,6 +3270,7 @@ class Blob(_PropertyMixin):
         if_source_generation_not_match=None,
         if_source_metageneration_match=None,
         if_source_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
     ):
         """Rewrite source blob into this one.
@@ -3376,37 +3292,29 @@ class Blob(_PropertyMixin):
             (Optional) The client to use.  If not passed, falls back to the
             ``client`` stored on the blob's bucket.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current generation matches the given value.
-            Setting to 0 makes the operation succeed only if there are no live
-            versions of the object.
+            (Optional) See :ref:`using-if-generation-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current generation does not match the given
-            value. If no live object exists, the precondition fails. Setting to
-            0 makes the operation succeed only if there is a live version of
-            the object.
+            (Optional) See :ref:`using-if-generation-not-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current metageneration matches the given
-            value.
+            (Optional) See :ref:`using-if-metageneration-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current metageneration does not match the
-            given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_source_generation_match: long
         :param if_source_generation_match:
@@ -3428,6 +3336,11 @@ class Blob(_PropertyMixin):
             (Optional) Makes the operation conditional on whether the source
             object's current metageneration does not match the given value.
 
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
+
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
             (Optional) How to retry the RPC. See: :ref:`configuring_retries`
@@ -3533,30 +3446,27 @@ class Blob(_PropertyMixin):
 
         :type if_generation_match: long
         :param if_generation_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current generation matches the given value.
-            Setting to 0 makes the operation succeed only if there are no live
-            versions of the object.
+            (Optional) See :ref:`using-if-generation-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_generation_not_match: long
         :param if_generation_not_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current generation does not match the given
-            value. If no live object exists, the precondition fails. Setting to
-            0 makes the operation succeed only if there is a live version of
-            the object.
+            (Optional) See :ref:`using-if-generation-not-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_match: long
         :param if_metageneration_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current metageneration matches the given
-            value.
+            (Optional) See :ref:`using-if-metageneration-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_not_match: long
         :param if_metageneration_not_match:
-            (Optional) Makes the operation conditional on whether the
-            destination object's current metageneration does not match the
-            given value.
+            (Optional) See :ref:`using-if-metageneration-not-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_source_generation_match: long
         :param if_source_generation_match:
@@ -3691,15 +3601,30 @@ class Blob(_PropertyMixin):
             newline mode" and writes use the system default. See the Python
             'io' module documentation for 'io.TextIOWrapper' for details.
 
-        :param kwargs: Keyword arguments to pass to the underlying API calls.
+        :param kwargs:
+            Keyword arguments to pass to the underlying API calls.
             For both uploads and downloads, the following arguments are
-            supported: "if_generation_match", "if_generation_not_match",
-            "if_metageneration_match", "if_metageneration_not_match", "timeout",
-            "retry". For uploads only, the following additional arguments are
-            supported: "content_type", "num_retries", "predefined_acl",
-            "checksum". "num_retries" is supported for backwards-compatibility
-            reasons only; please use "retry" with a Retry object or
-            ConditionalRetryPolicy instead.
+            supported:
+
+            - ``if_generation_match``
+            - ``if_generation_not_match``
+            - ``if_metageneration_match``
+            - ``if_metageneration_not_match``
+            - ``timeout``
+            - ``retry``
+
+            For uploads only, the following additional arguments are supported:
+
+            - ``content_type``
+            - ``num_retries``
+            - ``predefined_acl``
+            - ``checksum``
+
+            .. note::
+
+               ``num_retries`` is supported for backwards-compatibility
+               reasons only; please use ``retry`` with a Retry object or
+               ConditionalRetryPolicy instead.
 
         :returns: A 'BlobReader' or 'BlobWriter' from
             'google.cloud.storage.fileio', or an 'io.TextIOWrapper' around one
diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py
index a4a27d7..0dc4ef7 100644
--- a/google/cloud/storage/bucket.py
+++ b/google/cloud/storage/bucket.py
@@ -1045,11 +1045,11 @@ class Bucket(_PropertyMixin):
         client=None,
         encryption_key=None,
         generation=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY,
         **kwargs
     ):
@@ -1079,34 +1079,29 @@ class Bucket(_PropertyMixin):
             https://cloud.google.com/storage/docs/encryption#customer-supplied.
 
         :type generation: long
-        :param generation: (Optional) If present, selects a specific revision of
-                           this object.
-
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
+        :param generation:
+            (Optional) If present, selects a specific revision of this object.
 
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -1454,11 +1449,11 @@ class Bucket(_PropertyMixin):
         blob_name,
         client=None,
         generation=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
         if_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
     ):
         """Deletes a blob from the current bucket.
@@ -1487,31 +1482,26 @@ class Bucket(_PropertyMixin):
         :param generation: (Optional) If present, permanently deletes a specific
                            revision of this object.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -1581,35 +1571,31 @@ class Bucket(_PropertyMixin):
         :param client: (Optional) The client to use.  If not passed, falls back
                        to the ``client`` stored on the current bucket.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: list of long
-        :param if_generation_match: (Optional) Make the operation conditional on whether
-                                    the blob's current generation matches the given value.
-                                    Setting to 0 makes the operation succeed only if there
-                                    are no live versions of the blob. The list must match
-                                    ``blobs`` item-to-item.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
+            Note that the length of the list must match the length of
+            The list must match ``blobs`` item-to-item.
 
         :type if_generation_not_match: list of long
-        :param if_generation_not_match: (Optional) Make the operation conditional on whether
-                                        the blob's current generation does not match the given
-                                        value. If no live blob exists, the precondition fails.
-                                        Setting to 0 makes the operation succeed only if there
-                                        is a live version of the blob. The list must match
-                                        ``blobs`` item-to-item.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
+            The list must match ``blobs`` item-to-item.
 
         :type if_metageneration_match: list of long
-        :param if_metageneration_match: (Optional) Make the operation conditional on whether the
-                                        blob's current metageneration matches the given value.
-                                        The list must match ``blobs`` item-to-item.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
+            The list must match ``blobs`` item-to-item.
 
         :type if_metageneration_not_match: list of long
-        :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
-                                            blob's current metageneration does not match the given value.
-                                            The list must match ``blobs`` item-to-item.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+            The list must match ``blobs`` item-to-item.
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -1673,7 +1659,6 @@ class Bucket(_PropertyMixin):
         client=None,
         preserve_acl=True,
         source_generation=None,
-        timeout=_DEFAULT_TIMEOUT,
         if_generation_match=None,
         if_generation_not_match=None,
         if_metageneration_match=None,
@@ -1682,6 +1667,7 @@ class Bucket(_PropertyMixin):
         if_source_generation_not_match=None,
         if_source_metageneration_match=None,
         if_source_metageneration_not_match=None,
+        timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
     ):
         """Copy the given blob to the given bucket, optionally with a new name.
@@ -1712,67 +1698,54 @@ class Bucket(_PropertyMixin):
         :param source_generation: (Optional) The generation of the blob to be
                                   copied.
 
-        :type timeout: float or tuple
-        :param timeout:
-            (Optional) The amount of time, in seconds, to wait
-            for the server response.  See: :ref:`configuring_timeouts`
-
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Makes the operation
-                                    conditional on whether the destination
-                                    object's current generation matches the
-                                    given value. Setting to 0 makes the
-                                    operation succeed only if there are no
-                                    live versions of the object.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Makes the operation
-                                        conditional on whether the
-                                        destination object's current
-                                        generation does not match the given
-                                        value. If no live object exists,
-                                        the precondition fails. Setting to
-                                        0 makes the operation succeed only
-                                        if there is a live version
-                                        of the object.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Makes the operation
-                                        conditional on whether the
-                                        destination object's current
-                                        metageneration matches the given
-                                        value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Makes the operation
-                                            conditional on whether the
-                                            destination object's current
-                                            metageneration does not match
-                                            the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_source_generation_match: long
-        :param if_source_generation_match: (Optional) Makes the operation
-                                           conditional on whether the source
-                                           object's generation matches the
-                                           given value.
+        :param if_source_generation_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's generation matches the given value.
 
         :type if_source_generation_not_match: long
-        :param if_source_generation_not_match: (Optional) Makes the operation
-                                               conditional on whether the source
-                                               object's generation does not match
-                                               the given value.
+        :param if_source_generation_not_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's generation does not match the given value.
 
         :type if_source_metageneration_match: long
-        :param if_source_metageneration_match: (Optional) Makes the operation
-                                               conditional on whether the source
-                                               object's current metageneration
-                                               matches the given value.
+        :param if_source_metageneration_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's current metageneration matches the given value.
 
         :type if_source_metageneration_not_match: long
-        :param if_source_metageneration_not_match: (Optional) Makes the operation
-                                                   conditional on whether the source
-                                                   object's current metageneration
-                                                   does not match the given value.
+        :param if_source_metageneration_not_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's current metageneration does not match the given value.
+
+        :type timeout: float or tuple
+        :param timeout:
+            (Optional) The amount of time, in seconds, to wait
+            for the server response.  See: :ref:`configuring_timeouts`
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
@@ -1880,65 +1853,52 @@ class Bucket(_PropertyMixin):
                        to the ``client`` stored on the current bucket.
 
         :type if_generation_match: long
-        :param if_generation_match: (Optional) Makes the operation
-                                    conditional on whether the destination
-                                    object's current generation matches the
-                                    given value. Setting to 0 makes the
-                                    operation succeed only if there are no
-                                    live versions of the object.
+        :param if_generation_match:
+            (Optional) See :ref:`using-if-generation-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_generation_not_match: long
-        :param if_generation_not_match: (Optional) Makes the operation
-                                        conditional on whether the
-                                        destination object's current
-                                        generation does not match the given
-                                        value. If no live object exists,
-                                        the precondition fails. Setting to
-                                        0 makes the operation succeed only
-                                        if there is a live version
-                                        of the object.
+        :param if_generation_not_match:
+            (Optional) See :ref:`using-if-generation-not-match`
+            Note that the generation to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_match: long
-        :param if_metageneration_match: (Optional) Makes the operation
-                                        conditional on whether the
-                                        destination object's current
-                                        metageneration matches the given
-                                        value.
+        :param if_metageneration_match:
+            (Optional) See :ref:`using-if-metageneration-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_metageneration_not_match: long
-        :param if_metageneration_not_match: (Optional) Makes the operation
-                                            conditional on whether the
-                                            destination object's current
-                                            metageneration does not match
-                                            the given value.
+        :param if_metageneration_not_match:
+            (Optional) See :ref:`using-if-metageneration-not-match`
+            Note that the metageneration to be matched is that of the
+            ``destination`` blob.
 
         :type if_source_generation_match: long
-        :param if_source_generation_match: (Optional) Makes the operation
-                                           conditional on whether the source
-                                           object's generation matches the
-                                           given value. Also used in the
-                                           delete request.
+        :param if_source_generation_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's generation matches the given value. Also used in the
+            (implied) delete request.
 
         :type if_source_generation_not_match: long
-        :param if_source_generation_not_match: (Optional) Makes the operation
-                                               conditional on whether the source
-                                               object's generation does not match
-                                               the given value. Also used in the
-                                               delete request.
+        :param if_source_generation_not_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's generation does not match the given value. Also used in
+            the (implied) delete request.
 
         :type if_source_metageneration_match: long
-        :param if_source_metageneration_match: (Optional) Makes the operation
-                                               conditional on whether the source
-                                               object's current metageneration
-                                               matches the given value.Also used in the
-                                               delete request.
+        :param if_source_metageneration_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's current metageneration matches the given value. Also used
+            in the (implied) delete request.
 
         :type if_source_metageneration_not_match: long
-        :param if_source_metageneration_not_match: (Optional) Makes the operation
-                                                   conditional on whether the source
-                                                   object's current metageneration
-                                                   does not match the given value.
-                                                   Also used in the delete request.
+        :param if_source_metageneration_not_match:
+            (Optional) Makes the operation conditional on whether the source
+            object's current metageneration does not match the given value.
+            Also used in the (implied) delete request.
 
         :type timeout: float or tuple
         :param timeout:
diff --git a/google/cloud/storage/client.py b/google/cloud/storage/client.py
index df42f0c..d6f688d 100644
--- a/google/cloud/storage/client.py
+++ b/google/cloud/storage/client.py
@@ -983,37 +983,35 @@ class Client(ClientWithProject):
              str, \
             ]):
                 The blob resource to pass or URI to download.
+
             file_obj (file):
                 A file handle to which to write the blob's data.
+
             start (int):
                 (Optional) The first byte in a range to be downloaded.
+
             end (int):
                 (Optional) The last byte in a range to be downloaded.
+
             raw_download (bool):
                 (Optional) If true, download the object without any expansion.
-            if_generation_match (long):
-                (Optional) Make the operation conditional on whether
-                the blob's current generation matches the given value.
-                Setting to 0 makes the operation succeed only if there
-                are no live versions of the blob.
-            if_generation_not_match (long):
-                (Optional) Make the operation conditional on whether
-                the blob's current generation does not match the given
-                value. If no live blob exists, the precondition fails.
-                Setting to 0 makes the operation succeed only if there
-                is a live version of the blob.
-            if_metageneration_match (long):
-                (Optional) Make the operation conditional on whether the
-                blob's current metageneration matches the given value.
-            if_metageneration_not_match (long):
-                (Optional) Make the operation conditional on whether the
-                blob's current metageneration does not match the given value.
+
+            if_generation_match: long
+                (Optional) See :ref:`using-if-generation-match`
+
+            if_generation_not_match: long
+                (Optional) See :ref:`using-if-generation-not-match`
+
+            if_metageneration_match: long
+                (Optional) See :ref:`using-if-metageneration-match`
+
+            if_metageneration_not_match: long
+                (Optional) See :ref:`using-if-metageneration-not-match`
+
             timeout ([Union[float, Tuple[float, float]]]):
-                (Optional) The number of seconds the transport should wait for the
-                server response. Depending on the retry strategy, a request may be
-                repeated several times using the same timeout each time.
-                Can also be passed as a tuple (connect_timeout, read_timeout).
-                See :meth:`requests.Session.request` documentation for details.
+                (Optional) The amount of time, in seconds, to wait
+                for the server response.  See: :ref:`configuring_timeouts`
+
             checksum (str):
                 (Optional) The type of checksum to compute to verify the integrity
                 of the object. The response headers must contain a checksum of the
diff --git a/google/cloud/storage/fileio.py b/google/cloud/storage/fileio.py
index e74b9ed..6ac8e05 100644
--- a/google/cloud/storage/fileio.py
+++ b/google/cloud/storage/fileio.py
@@ -67,7 +67,8 @@ class BlobReader(io.BufferedIOBase):
         The default is the chunk_size of the blob, or 40MiB.
 
     :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
-    :param retry: (Optional) How to retry the RPC. A None value will disable
+    :param retry:
+        (Optional) How to retry the RPC. A None value will disable
         retries. A google.api_core.retry.Retry value will enable retries,
         and the object will define retriable response codes and errors and
         configure backoff and timeout options.
@@ -88,10 +89,15 @@ class BlobReader(io.BufferedIOBase):
         configuration changes for Retry objects such as delays and deadlines
         are respected.
 
-    :param download_kwargs: Keyword arguments to pass to the underlying API
-        calls. The following arguments are supported: "if_generation_match",
-        "if_generation_not_match", "if_metageneration_match",
-        "if_metageneration_not_match", "timeout".
+    :param download_kwargs:
+        Keyword arguments to pass to the underlying API calls.
+        The following arguments are supported:
+
+        - ``if_generation_match``
+        - ``if_generation_not_match``
+        - ``if_metageneration_match``
+        - ``if_metageneration_not_match``
+        - ``timeout``
     """
 
     def __init__(self, blob, chunk_size=None, retry=DEFAULT_RETRY, **download_kwargs):
@@ -230,7 +236,8 @@ class BlobWriter(io.BufferedIOBase):
         expectations.
 
     :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
-    :param retry: (Optional) How to retry the RPC. A None value will disable
+    :param retry:
+        (Optional) How to retry the RPC. A None value will disable
         retries. A google.api_core.retry.Retry value will enable retries,
         and the object will define retriable response codes and errors and
         configure backoff and timeout options.
@@ -251,11 +258,19 @@ class BlobWriter(io.BufferedIOBase):
         configuration changes for Retry objects such as delays and deadlines
         are respected.
 
-    :param upload_kwargs: Keyword arguments to pass to the underlying API
-        calls. The following arguments are supported: "if_generation_match",
-        "if_generation_not_match", "if_metageneration_match",
-        "if_metageneration_not_match", "timeout", "content_type",
-        "num_retries", "predefined_acl", "checksum".
+    :param upload_kwargs:
+        Keyword arguments to pass to the underlying API
+        calls. The following arguments are supported:
+
+        - ``if_generation_match``
+        - ``if_generation_not_match``
+        - ``if_metageneration_match``
+        - ``if_metageneration_not_match``
+        - ``timeout``
+        - ``content_type``
+        - ``num_retries``
+        - ``predefined_acl``
+        - ``checksum``
     """
 
     def __init__(
diff --git a/noxfile.py b/noxfile.py
index 0b85dc8..c34e8b9 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -179,6 +179,7 @@ def docfx(session):
     """Build the docfx yaml files for this library."""
 
     session.install("-e", ".")
+    session.install("grpcio")
     session.install("sphinx", "alabaster", "recommonmark", "gcp-sphinx-docfx-yaml")
 
     shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)


Test patch:
diff --git a/tests/unit/test_blob.py b/tests/unit/test_blob.py
index 1581097..a213858 100644
--- a/tests/unit/test_blob.py
+++ b/tests/unit/test_blob.py
@@ -3996,7 +3996,9 @@ class Test_Blob(unittest.TestCase):
         )
 
     @mock.patch("warnings.warn")
-    def test_compose_w_generation_match_w_warning(self, mock_warn):
+    def test_compose_w_if_generation_match_list_w_warning(self, mock_warn):
+        from google.cloud.storage.blob import _COMPOSE_IF_GENERATION_LIST_DEPRECATED
+
         source_1_name = "source-1"
         source_2_name = "source-2"
         destination_name = "destination"
@@ -4045,13 +4047,10 @@ class Test_Blob(unittest.TestCase):
         )
 
         mock_warn.assert_called_with(
-            "if_generation_match: type list is deprecated and supported for backwards-compatability reasons only."
-            "Use if_source_generation_match instead to match source objects generations.",
-            DeprecationWarning,
-            stacklevel=2,
+            _COMPOSE_IF_GENERATION_LIST_DEPRECATED, DeprecationWarning, stacklevel=2,
         )
 
-    def test_compose_invalid_generation_match(self):
+    def test_compose_w_if_generation_match_and_if_s_generation_match(self):
         source_1_name = "source-1"
         source_2_name = "source-2"
         destination_name = "destination"
@@ -4073,7 +4072,9 @@ class Test_Blob(unittest.TestCase):
         client._post_resource.assert_not_called()
 
     @mock.patch("warnings.warn")
-    def test_compose_w_metageneration_match_w_warning(self, mock_warn):
+    def test_compose_w_if_metageneration_match_list_w_warning(self, mock_warn):
+        from google.cloud.storage.blob import _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED
+
         source_1_name = "source-1"
         source_2_name = "source-2"
         destination_name = "destination"
@@ -4108,9 +4109,7 @@ class Test_Blob(unittest.TestCase):
         )
 
         mock_warn.assert_called_with(
-            "if_metageneration_match: type list is deprecated and supported for backwards-compatability reasons only."
-            "Note that the metageneration to be matched is that of the destination blob."
-            "Please pass in a single value (type long).",
+            _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED,
             DeprecationWarning,
             stacklevel=2,
         )