docs: render fields correctly for update calls (#2055)

leahecole · web-flow · commit a4d9534a900f · 2024-11-07T15:56:57.000-05:00
diff --git a/google/cloud/bigquery/client.py b/google/cloud/bigquery/client.py
@@ -1184,6 +1184,19 @@ def update_dataset(
         must be provided. If a field is listed in ``fields`` and is ``None`` in
         ``dataset``, it will be deleted.
 
+        For example, to update the default expiration times, specify
+        both properties in the ``fields`` argument:
+
+        .. code-block:: python
+
+            bigquery_client.update_dataset(
+                dataset,
+                [
+                    "default_partition_expiration_ms",
+                    "default_table_expiration_ms",
+                ]
+            )
+
         If ``dataset.etag`` is not ``None``, the update will only
         succeed if the dataset on the server has the same ETag. Thus
         reading a dataset with ``get_dataset``, changing its fields,
@@ -1198,19 +1211,6 @@ def update_dataset(
                 The properties of ``dataset`` to change. These are strings
                 corresponding to the properties of
                 :class:`~google.cloud.bigquery.dataset.Dataset`.
-
-                For example, to update the default expiration times, specify
-                both properties in the ``fields`` argument:
-
-                .. code-block:: python
-
-                    bigquery_client.update_dataset(
-                        dataset,
-                        [
-                            "default_partition_expiration_ms",
-                            "default_table_expiration_ms",
-                        ]
-                    )
             retry (Optional[google.api_core.retry.Retry]):
                 How to retry the RPC.
             timeout (Optional[float]):
@@ -1254,6 +1254,15 @@ def update_model(
         must be provided. If a field is listed in ``fields`` and is ``None``
         in ``model``, the field value will be deleted.
 
+        For example, to update the descriptive properties of the model,
+        specify them in the ``fields`` argument:
+
+        .. code-block:: python
+
+            bigquery_client.update_model(
+                model, ["description", "friendly_name"]
+            )
+
         If ``model.etag`` is not ``None``, the update will only succeed if
         the model on the server has the same ETag. Thus reading a model with
         ``get_model``, changing its fields, and then passing it to
@@ -1266,15 +1275,6 @@ def update_model(
                 The properties of ``model`` to change. These are strings
                 corresponding to the properties of
                 :class:`~google.cloud.bigquery.model.Model`.
-
-                For example, to update the descriptive properties of the model,
-                specify them in the ``fields`` argument:
-
-                .. code-block:: python
-
-                    bigquery_client.update_model(
-                        model, ["description", "friendly_name"]
-                    )
             retry (Optional[google.api_core.retry.Retry]):
                 A description of how to retry the API call.
             timeout (Optional[float]):
@@ -1318,6 +1318,15 @@ def update_routine(
         must be provided. If a field is listed in ``fields`` and is ``None``
         in ``routine``, the field value will be deleted.
 
+        For example, to update the description property of the routine,
+        specify it in the ``fields`` argument:
+
+        .. code-block:: python
+
+            bigquery_client.update_routine(
+                routine, ["description"]
+            )
+
         .. warning::
            During beta, partial updates are not supported. You must provide
            all fields in the resource.
@@ -1336,15 +1345,6 @@ def update_routine(
             fields (Sequence[str]):
                 The fields of ``routine`` to change, spelled as the
                 :class:`~google.cloud.bigquery.routine.Routine` properties.
-
-                For example, to update the description property of the routine,
-                specify it in the ``fields`` argument:
-
-                .. code-block:: python
-
-                    bigquery_client.update_routine(
-                        routine, ["description"]
-                    )
             retry (Optional[google.api_core.retry.Retry]):
                 A description of how to retry the API call.
             timeout (Optional[float]):
@@ -1392,6 +1392,16 @@ def update_table(
         must be provided. If a field is listed in ``fields`` and is ``None``
         in ``table``, the field value will be deleted.
 
+        For example, to update the descriptive properties of the table,
+        specify them in the ``fields`` argument:
+
+        .. code-block:: python
+
+            bigquery_client.update_table(
+                table,
+                ["description", "friendly_name"]
+            )
+
         If ``table.etag`` is not ``None``, the update will only succeed if
         the table on the server has the same ETag. Thus reading a table with
         ``get_table``, changing its fields, and then passing it to
@@ -1403,16 +1413,6 @@ def update_table(
             fields (Sequence[str]):
                 The fields of ``table`` to change, spelled as the
                 :class:`~google.cloud.bigquery.table.Table` properties.
-
-                For example, to update the descriptive properties of the table,
-                specify them in the ``fields`` argument:
-
-                .. code-block:: python
-
-                    bigquery_client.update_table(
-                        table,
-                        ["description", "friendly_name"]
-                    )
             retry (Optional[google.api_core.retry.Retry]):
                 A description of how to retry the API call.
             timeout (Optional[float]):
