Docs/fixit: normalize docs for 'page_size' / 'max_results' / 'page_to…

…ken' (#6842)

bigquery/google/cloud/bigquery/client.py

@@ -1674,8 +1674,9 @@ def list_rows(
             start_index (int):
                 (Optional) The zero-based index of the starting row to read.
             page_size (int):
-                (Optional) The maximum number of items to return per page in
-                the iterator.
+                Optional. The maximum number of rows in each page of results
+                from this request. Non-positive values are ignored. Defaults
+                to a sensible value set by the API.
             retry (:class:`google.api_core.retry.Retry`):
                 (Optional) How to retry the RPC.
 

bigquery/google/cloud/bigquery/table.py

@@ -1240,7 +1240,9 @@ class RowIterator(HTTPIterator):
         page_token (str): A token identifying a page in a result set to start
             fetching results from.
         max_results (int, optional): The maximum number of results to fetch.
-        page_size (int, optional): The number of items to return per page.
+        page_size (int, optional): The maximum number of rows in each page
+            of results from this request. Non-positive values are ignored.
+            Defaults to a sensible value set by the API.
         extra_params (Dict[str, object]):
             Extra query string parameters for the API call.
         table (Union[ \

dns/google/cloud/dns/client.py

@@ -82,9 +82,11 @@ def list_zones(self, max_results=None, page_token=None):
                             passed, defaults to a value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of zones. If
-                           not passed, the API will return the first page of
-                           zones.
+        :param page_token: Optional. If present, return the next batch of
+            zones, using the value, which must correspond to the
+            ``nextPageToken`` value returned in the previous response.
+            Deprecated: use the ``pages`` property of the returned iterator
+            instead of manually passing the token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of :class:`~google.cloud.dns.zone.ManagedZone`

dns/google/cloud/dns/zone.py

@@ -325,13 +325,16 @@ def list_resource_record_sets(self, max_results=None, page_token=None, client=No
         https://cloud.google.com/dns/api/v1/resourceRecordSets/list
 
         :type max_results: int
-        :param max_results: maximum number of zones to return, If not
-                            passed, defaults to a value set by the API.
+        :param max_results: Optional. The maximum number of resource record
+                            sets to return. Defaults to a sensible value
+                            set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of zones. If
-                           not passed, the API will return the first page of
-                           zones.
+        :param page_token: Optional. If present, return the next batch of
+            resource record sets, using the value, which must correspond to
+            the ``nextPageToken`` value returned in the previous response.
+            Deprecated: use the ``pages`` property of the returned iterator
+            instead of manually passing the token.
 
         :type client: :class:`google.cloud.dns.client.Client`
         :param client:
@@ -363,13 +366,15 @@ def list_changes(self, max_results=None, page_token=None, client=None):
         https://cloud.google.com/dns/api/v1/resourceRecordSets/list
 
         :type max_results: int
-        :param max_results: maximum number of zones to return, If not
-                            passed, defaults to a value set by the API.
+        :param max_results: Optional. The maximum number of change sets
+            to return. Defaults to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of zones. If
-                           not passed, the API will return the first page of
-                           zones.
+        :param page_token: Optional. If present, return the next batch of
+            change sets, using the value, which must correspond to the
+            ``nextPageToken`` value returned in the previous response.
+            Deprecated: use the ``pages`` property of the returned iterator
+            instead of manually passing the token.
 
         :type client: :class:`google.cloud.dns.client.Client`
         :param client:

firestore/google/cloud/firestore_v1beta1/document.py

@@ -459,7 +459,9 @@ def collections(self, page_size=None):
         """List subcollections of the current document.
 
         Args:
-            page_size (Optional[int]]): Iterator page size.
+            page_size (Optional[int]]): The maximum number of collections
+            in each page of results from this request. Non-positive values
+            are ignored. Defaults to a sensible value set by the API.
 
         Returns:
             Sequence[~.firestore_v1beta1.collection.CollectionReference]:

logging/google/cloud/logging/client.py

@@ -191,13 +191,18 @@ def list_entries(
                          or :data:`~google.cloud.logging.DESCENDING`.
 
         :type page_size: int
-        :param page_size: maximum number of entries to return, If not passed,
-                          defaults to a value set by the API.
+        :param page_size:
+            Optional. The maximum number of entries in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of entries. If not
-                           passed, the API will return the first page of
-                           entries.
+        :param page_token:
+            Optional. If present, return the next batch of entries, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of :class:`~google.cloud.logging.entries._BaseEntry`
@@ -244,13 +249,18 @@ def list_sinks(self, page_size=None, page_token=None):
         https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/list
 
         :type page_size: int
-        :param page_size: maximum number of sinks to return, If not passed,
-                          defaults to a value set by the API.
+        :param page_size:
+            Optional. The maximum number of sinks in each page of results from
+            this request. Non-positive values are ignored. Defaults to a
+            sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of sinks. If not
-                           passed, the API will return the first page of
-                           sinks.
+        :param page_token:
+            Optional. If present, return the next batch of sinks, using the
+            value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing the
+            token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of
@@ -288,13 +298,18 @@ def list_metrics(self, page_size=None, page_token=None):
         https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.metrics/list
 
         :type page_size: int
-        :param page_size: maximum number of metrics to return, If not passed,
-                          defaults to a value set by the API.
+        :param page_size:
+            Optional. The maximum number of metrics in each page of results
+            from this request. Non-positive values are ignored. Defaults to a
+            sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of metrics. If not
-                           passed, the API will return the first page of
-                           metrics.
+        :param page_token:
+            Optional. If present, return the next batch of metrics, using the
+            value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing the
+            token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of :class:`~google.cloud.logging.metric.Metric`

logging/google/cloud/logging/logger.py

@@ -249,13 +249,18 @@ def list_entries(
                          or :data:`~google.cloud.logging.DESCENDING`.
 
         :type page_size: int
-        :param page_size: maximum number of entries to return, If not passed,
-                          defaults to a value set by the API.
+        :param page_size:
+            Optional. The maximum number of entries in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of entries. If not
-                           passed, the API will return the first page of
-                           entries.
+        :param page_token:
+            Optional. If present, return the next batch of entries, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of log entries accessible to the current logger.

monitoring/google/cloud/monitoring_v3/query.py

@@ -426,9 +426,9 @@ def iter(self, headers_only=False, page_size=None):
 
         :type page_size: int
         :param page_size:
-            (Optional) Positive number specifying the maximum number of points
-            to return per page. This can be used to control how far the
-            iterator reads ahead.
+            (Optional) The maximum number of points in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :raises: :exc:`ValueError` if the query time interval has not been
             specified.
@@ -450,7 +450,9 @@ def _build_query_params(self, headers_only=False, page_size=None):
 
         :type page_size: int
         :param page_size:
-            (Optional) A limit on the number of points to return per page.
+            (Optional) The maximum number of points in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
         """
         params = {"name": self._project_path, "filter_": self.filter}
 

resource_manager/google/cloud/resource_manager/client.py

@@ -146,9 +146,10 @@ def list_projects(self, filter_params=None, page_size=None):
                               details.
 
         :type page_size: int
-        :param page_size: (Optional) Maximum number of projects to return in a
-                          single page. If not passed, defaults to a value set
-                          by the API.
+        :param page_size: (Optional) The maximum number of projects in each
+                          page of results from this request. Non-positive
+                          values are ignored. Defaults to a sensible value
+                          set by the API.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of all

runtimeconfig/google/cloud/runtimeconfig/config.py

@@ -222,11 +222,17 @@ def list_variables(self, page_size=None, page_token=None, client=None):
 
         :type page_size: int
         :param page_size:
-            (Optional) Maximum number of variables to return per page.
+            Optional. The maximum number of variables in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: opaque marker for the next "page" of variables. If
-                           not passed, will return the first page of variables.
+        :param page_token:
+            Optional. If present, return the next batch of variables, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :type client: :class:`~google.cloud.runtimeconfig.client.Client`
         :param client:

spanner/google/cloud/spanner_v1/client.py

@@ -191,10 +191,18 @@ def list_instance_configs(self, page_size=None, page_token=None):
         See `RPC docs`_.
 
         :type page_size: int
-        :param page_size: (Optional) Maximum number of results to return.
+        :param page_size:
+            Optional. The maximum number of configs in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: (Optional) Token for fetching next page of results.
+        :param page_token:
+            Optional. If present, return the next batch of configs, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns:
@@ -256,10 +264,18 @@ def list_instances(self, filter_="", page_size=None, page_token=None):
                         the ``ListInstancesRequest`` docs above for examples.
 
         :type page_size: int
-        :param page_size: (Optional) Maximum number of results to return.
+        :param page_size:
+            Optional. The maximum number of instances in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: (Optional) Token for fetching next page of results.
+        :param page_token:
+            Optional. If present, return the next batch of instances, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns:

spanner/google/cloud/spanner_v1/instance.py

@@ -338,10 +338,18 @@ def list_databases(self, page_size=None, page_token=None):
         https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases
 
         :type page_size: int
-        :param page_size: (Optional) Maximum number of results to return.
+        :param page_size:
+            Optional. The maximum number of databases in each page of results
+            from this request. Non-positive values are ignored. Defaults
+            to a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: (Optional) Token for fetching next page of results.
+        :param page_token:
+            Optional. If present, return the next batch of databases, using
+            the value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing
+            the token.
 
         :rtype: :class:`~google.api._ore.page_iterator.Iterator`
         :returns:

storage/google/cloud/storage/bucket.py

@@ -623,12 +623,18 @@ def list_blobs(
         If :attr:`user_project` is set, bills the API request to that project.
 
         :type max_results: int
-        :param max_results: (Optional) Maximum number of blobs to return.
+        :param max_results:
+            (Optional) The maximum number of blobs in each page of results
+            from this request. Non-positive values are ignored. Defaults to
+            a sensible value set by the API.
 
         :type page_token: str
-        :param page_token: (Optional) Opaque marker for the next "page" of
-                           blobs. If not passed, will return the first page
-                           of blobs.
+        :param page_token:
+            (Optional) If present, return the next batch of blobs, using the
+            value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing the
+            token.
 
         :type prefix: str
         :param prefix: (Optional) prefix used to filter blobs.

storage/google/cloud/storage/client.py

@@ -308,12 +308,15 @@ def list_buckets(
         This implements "storage.buckets.list".
 
         :type max_results: int
-        :param max_results: Optional. Maximum number of buckets to return.
+        :param max_results: Optional. The maximum number of buckets to return.
 
         :type page_token: str
-        :param page_token: Optional. Opaque marker for the next "page" of
-                           buckets. If not passed, will return the first page
-                           of buckets.
+        :param page_token:
+            Optional. If present, return the next batch of buckets, using the
+            value, which must correspond to the ``nextPageToken`` value
+            returned in the previous response.  Deprecated: use the ``pages``
+            property of the returned iterator instead of manually passing the
+            token.
 
         :type prefix: str
         :param prefix: Optional. Filter results to buckets whose names begin