Repository: googleapis/google-cloud-python

Issue:
BigQuery: 'properties' parameter in google.cloud.bigquery.client.Client.update_table is not documented
'properties' parameter in google.cloud.bigquery.client.Client.update_table is not documented.
The body of the description is also inaccurate as it always does a PATCH request.
See: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/reference.html#google.cloud.bigquery.client.Client.update_table



Discussion:
ASIDE: Our `pylint` configuration used to make sure `Args` matched the inputs.
Thanks for the report. You're absolutely right that we missed updating the docs for this method.

The way the properties parameter is used is as a list of strings, as is used in the `fields` parameter of [`update_dataset`](https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/reference.html#google.cloud.bigquery.client.Client.update_dataset)

We should probably choose consistent names between `update_dataset` and `update_table` for this, too. Since we've already put people through a lot of breaking changes, I propose we deprecate `properties` for one version (replaced by `fields`) and remove `properties` later.

Resolving patch:
diff --git a/bigquery/google/cloud/bigquery/client.py b/bigquery/google/cloud/bigquery/client.py
--- a/bigquery/google/cloud/bigquery/client.py
+++ b/bigquery/google/cloud/bigquery/client.py
@@ -313,7 +313,7 @@ def update_dataset(self, dataset, fields, retry=DEFAULT_RETRY):
         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,
-        and then passing it ``update_dataset`` will ensure that the changes
+        and then passing it to ``update_dataset`` will ensure that the changes
         will only be saved if no modifications to the dataset occurred
         since the read.
 
@@ -353,23 +353,32 @@ def update_dataset(self, dataset, fields, retry=DEFAULT_RETRY):
             retry, method='PATCH', path=path, data=partial, headers=headers)
         return Dataset.from_api_repr(api_response)
 
-    def update_table(self, table, properties, retry=DEFAULT_RETRY):
-        """API call:  update table properties via a PUT request
+    def update_table(self, table, fields, retry=DEFAULT_RETRY):
+        """Change some fields of a table.
 
-        See
-        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/update
-
-        :type table:
-            :class:`google.cloud.bigquery.table.Table`
-        :param table_ref: the table to update.
-
-        :type retry: :class:`google.api_core.retry.Retry`
-        :param retry: (Optional) How to retry the RPC.
-
-        :rtype: :class:`google.cloud.bigquery.table.Table`
-        :returns: a ``Table`` instance
+        Use ``fields`` to specify which fields to update. At least one field
+        must be provided. If a field is listed in ``fields`` and is ``None``
+        in ``table``, it will be deleted.
+
+        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
+        ``update_table`` will ensure that the changes will only be saved if
+        no modifications to the table occurred since the read.
+
+        Args:
+            table (google.cloud.bigquery.table.Table): The table to update.
+            fields (Sequence[str]):
+                The fields of ``table`` to change, spelled as the Table
+                properties (e.g. "friendly_name").
+            retry (google.api_core.retry.Retry):
+                (Optional) A description of how to retry the API call.
+
+        Returns:
+            google.cloud.bigquery.table.Table:
+                The table resource returned from the API call.
         """
-        partial = table._build_resource(properties)
+        partial = table._build_resource(fields)
         if table.etag is not None:
             headers = {'If-Match': table.etag}
         else:


Test patch: