Document client.dataset() deprecation.

Now that all client methods that take a `DatasetReference` or
`TableReference` also take a string, the `client.dataset()` method is
unnecessary and confusing.

Author: tswast

bigquery/google/cloud/bigquery/client.py

@@ -288,7 +288,18 @@ def list_datasets(
         )
 
     def dataset(self, dataset_id, project=None):
-        """Construct a reference to a dataset.
+        """Deprecated: Construct a reference to a dataset.
+
+        This method is deprecated. Construct a
+        :class:`~google.cloud.bigquery.dataset.DatasetReference` using its
+        constructor or use a string where previously a reference object was
+        used.
+
+        As ``google-cloud-bigquery`` version 1.7.0, all client methods that
+        take a :class:`~google.cloud.bigquery.dataset.DatasetReference` or
+        :class:`~google.cloud.bigquery.table.TableReference` also take a
+        string in standard SQL format, e.g. ``project.dataset_id`` or
+        ``project.dataset_id.table_id``.
 
         :type dataset_id: str
         :param dataset_id: ID of the dataset.