Repository navigation
[general] Documentation on page_size is very minimal. #6207
Description
The explanation of page_size is extremely limited.
Example from the logging API:
maximum number of entries to return, If not passed, defaults to a value set by the API.
If you're familiar with gRPC then this makes sense, but for newcomers this is extremely limited information. Simple wording change can make a lot of difference here IMHO. Looking at this example from the Cloud Spanner Javadocs shows a slight change, but makes it easier to understand:
Specifying this will cause the list operations to fetch at most this many records in a page.
On a semi-related note, having usage examples would also clarify the usage a lot, but this can be said for all methods in the whole python library.
Activity
Edo-A commentedon Oct 16, 2018
Another thing that needs attention as well is the related page_token. Wording is actually more confusing for this one: opaque marker?
The methods link to the page describing the API which has a much better description. Copying those into the lib itself would actually solve the issue without actually having to write up something new. Compare the following:
• page_size
From the lib:
maximum number of entries to return, If not passed, defaults to a value set by the API.From the API description:
Optional. The maximum number of results to return from this request. Non-positive values are ignored. The presence of nextPageToken in the response indicates that more results might be available.• page_token
From the lib:
opaque marker for the next "page" of entries. If not passed, the API will return the first page of entries.From the API description:
Optional. If present, then retrieve the next batch of results from the preceding call to this method. pageToken must be the value of nextPageToken from the previous response. The values of other method parameters should be identical to those in the previous call.tseaver commentedon Dec 4, 2018
@Edo-A note that we actually don't really expect / want users to pass either value explicitly in normal usage: the
list_foomethods return iterators which provide a much better surface for processing results, either item-by-item or page-at-a-time.page_sizemight be useful to override the APIs default in some very unusual cases (but it seems dubious).I'm going to say we should docs-deprecate
page_tokeneverywhere in non-generated code, with a note to use the iterator'spagesproperty if paging is desired.I'm going to scope this one to ignore occurrences of
page_size/page_tokenin GAPIC- or protoc-generated code.For
page_size:For
page_token: