Improve the documentation about the possible parameters of items.iter()

[Gallaecio]

I’m trying to understand the possible parameters of Job.items.iter() but it’s not that clear to me:

• Why is count documented as a parameter on its own? (I assume the rest of the pagination parameters are assumed to be part of apiparameters)
• What is requests_params for?
• I see other parameters mentioned in the documentation that don’t seem part of the Items API, pagination or meta. For example, filter (in the 4th example of the Items documentation, with list instead of iter but I assume they accept the same arguments)

[vshlapakov]

Hey @Gallaecio, these are pretty good questions, let me try to answer and we'll see if there's some room for improvements (I believe there's):

• re: count parameter: it's documented separately, as we want to put emphasis that it's important to use this parameter whenever it's possible. Using other parameters is up to you, but limiting your selection is a key thing, at least from UX point of view.

• apiparameters are SH API related parameters, like count/startts etc. It's contrasted with requests_params: we rely on requests library to send HTTP requests to our API, and there's a ton of additional parameters which can be sent along with the core ones (like url/method etc) which could be helpful if you need to customize the request behavior

• the filter parameter is a special one: despite there're some examples in the documentation on how to use it, we want to optimize some internal processes before we document it completely as a full-blown feature, so it should be considered as a supplementary for now, to combine it with other filtering parameters

• and yes, iter and list methods accept exactly the same sets of arguments.

[realslimshanky-sh]

Adding one more point as I think it's part of what this issue is about.
job.items.list_iter(chunksize=items_per_batch)) doesn’t seem to work correctly when there’s filter argument involved.

items = job.items.list_iter(chunksize=1, filter=filters)
items.__next__()
items.__next__()
items.__next__()

All the iterations return the same item. Maybe this is missed in the documentation or is it not a supported feature?