[Documentation]: We should have documentation on how to write leader-follower iterator pairs

[lydia-duncan]

Summary of Problem

Description:

Our documentation on iterators today mostly seems to focus on using them. I checked the spec chapter, iterators primer, and user's guide section on iterators and they all were far more focused on writing code that uses already existing iterators, but what I was looking for was how to write the leader-follower pair.

I know we want to eventually get to designing leader-follower 2.0 so at that point this effort would be moot, but it would have been helpful for me to have some documentation on our current system instead of needing to ask people or trying to guess based on code that was already present (where I did the latter).

Things I would have liked documentation on:

• How do the leader and follower interact?
  • It looks like the leader determines the space to iterate through and the follower yields from that space
  • It also looks like the leader will call a follower on itself in addition to a follower on whatever it is zipped with. This would have been nice to be explicitly explained instead of something I found out via writeln.
• What are some common ways to divide up the iteration space?
• What tools are commonly used when writing up leader-follower pairs? Things like computeNumChunks, maxTaskPar

I'm sure there's more that would be helpful to have. A focus on how to write the pair from the perspective of a collection author would have been helpful for me (since this came up in the context of working on #15824), but I'm sure we can think of other scenarios where someone would want to write an iterator. I'd also guess that pain points encountered when doing this documentation exercise would be helpful when designing leader-follower 2.0.

[bradcray]

Did your check of the iterators primer include https://chapel-lang.org/docs/primers/parIters.html? I know it strives to teach the authoring of leader-follower iterators, though I'm sure it could be made better.

[lydia-duncan]

Ah, I think I missed that one. I grabbed the iterators primer through test/release/examples/primers so only tab completed to iterators rather than the parallel iterators one. Thanks, I'll take a look and either update this issue with what else I'd want or close it

[lydia-duncan]

It probably would be beneficial to link to the parallel iterator primer from the serial one, though maybe it already does and I missed it because it didn't jump out as what I was looking for in the .chpl file view. I assumed it was complete because it had mentions of parallel iteration scenarios in it