page_token parameter documentation is misleading #3928
Description
The page_token parameter to several api functions such as list_projects and list_jobs is documented as follows:
opaque marker for the next "page" of projects. If not passed, the API will return the first page of projects.
This is very misleading, as these functions return an HTTPIterator which if iterated on will seamlessly return multiple pages of results.
Only though experimentation did I determine that multiple pages of results are returned and that if I did want to make use of page_token I'd need to access it at the next_page_token of the HTTPIterator.
I think the documentation should be updated to better reflect that multiple pages can be fetched without touching the page_token and possibly include where to access page_token if someone does need to use it.