Needs example of using paginate, and explination that it is required

[oxinabox]

At no point in the docs does it mention that @paginate is basically required to be used for all calls that might return more than one thing.

Possibly we should actually always return a iterator like @paginate does .
But right now we don't.

I was wondering why get_pull_requests(forge, project_id) was only returning 20 things even though i knew their are like 100 pull reqests on that repo.
Docs for get_pull_requests never mentioned @paginate.
No example of it being used was anywhere,
but I tried
@paginate get_pull_requests(forge, project_id)
and that returned all my pull requests.