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