Seq vs. List - Iterable, instead?

[coke]

There are many cases in the docs where something is documented as returning a List, when it in fact returns a Seq these days.

My recommendation is that we spec these as returning an Iterable, not a particular class, and update roast and the docs to follow.

[librasteve]

Great idea, I 100% agree.

[arkiuat]

I've been working on documenting deepmap, duckmap, nodemap as routines in class Any (currently they are only documented as methods), and I noticed that while the method deepmap is documented as returning a List, in the two examples given it returns an Array and a Hash respectively.

Iterable is the most specific role shared in common by both Array and Hash, so I'd like to go ahead and document deepmap, at least, as returning Iterable, and the other two also if investigation bears that out.

[arkiuat]

Some but not all of those entries "documented as returning a List, when it in fact returns a Seq" have in fact been updated to Seq, and now {deep|duck|node}map are documented as returning Iterable in line with the suggestion presented here, which means the docs are currently in a kind of messy state policy-wise.

Now at the time I changed the *-map entries, they were still showing a return of List (when in fact they return a variety of Iterables depending on their argument), so this change wasn't problematic. And it wouldn't be problematic when updating any article stating that something returns a List when in fact it now returns a Seq, to change that documented return spec to Iterable.

My question is: if I'm updating an entry that accurately (but overspecifically by the policy proposed here) states that something returns Seq, is it okay to change the documented return spec to Iterable in that case?

Or do we need to wait for the changes to roast before making that kind of change in the documentation?

[coke]

I would like to see corresponding changes in roast for this

[lizmat]

This issue will be discussed in the first Raku Resolutions meeting, see more information at https://dev.to/lizmat/raku-resolutions-17g7

[arkiuat]

Just because perhaps I didn't make it clear above, I'd like to say that I strongly support this proposal.

[lizmat]

I think this makes a lot of sense: historically the documentation was intended to match the exact signatures possible. I think that's actually not needed for most documentation uses (or testing uses, for that matter).

Also, think of the future where a (runtime) optimizer might decide that a piece of code is being called lazily (or eager), and optimize this.

Also, one example: sort is documented to return a Seq. Even worse, there are roast tests for this. However, a sorted list is basically a List, because otherwise it couldn't be sorted. So sort is returning a Seq on a completely reified List, while it could just return the List and bypass the Seq altogether.

[ab5tract]

At the recent Resolve-a-thon, we agreed to the following:

1. Update the documentation to specify Iterable
2. Later, coinciding with the release of 6.e, update roast to expect Iterable