In List.rakudoc, clarify wording around the subroutine version of rotor

[schultzdavid]

https://docs.raku.org/type/List#routine_rotor

Changes:

• Rearrange lines to make clearer what was introduced with v6.e.

• Update signatures: what was \source is now \thing (v6.e on MoarVM version 2025.10).

• One substantial change: In the second signature, write **@cycle instead of *@cycle, because list arguments don't get flattened here (rather, each list counts as one Int — see example below), so that ** is more appropriate than *. (Of course, technically, it's neither, as the comment actual sig is **@cycle-and-thing but only due to Rakudo limitation explains — because actual slurpies can only come at the end — but even so the behavior is much more like ** than like *.)

Example for the last point:

> rotor( (7,8), 1, 2, 'a' .. 'h')  # the first list just counts as 2
((a b) (c) (d e) (f g) (h))

[coke]

If this signature compiles, the skip isn’t needed. Maybe just a rakudoc comment (hidden from the user) explaining why it’s not the same in the rakudo source.

[schultzdavid]

The skip and the comment were already introduced with @lizmat's edit. I've now tested it in the REPL, where this (the second) signature indeed doesn't compile, since there's a slurpy at the very beginning of the signature and then the required parameter \thing coming after it:

Cannot put required parameter thing after variadic parameters

[coke]

So for teaching purposes, we should consider this the correct signature, even though Rakudo itself can’t compile it?

[schultzdavid]

Good question about the didactics.

For understanding the routine rotor, I think this "as-if" signature really is the right choice. For example, the method signature at the very top reads

method rotor(*@cycle, Bool() :$partial --> Seq:D)

so that after its discussion, understanding the routine becomes very straightforward through the (technically wrong) signature

multi rotor(*@cycle, \source, Bool() :$partial --> Seq:D).

However, some visible note stating that this is just for teaching and technically illegal would certainly be good. I'll think of something. (Also, I might still have to adapt * to ** in the method signature at the top, or rather to + it seems.)