API: long lists of `document` arguments are hard to guess from type output

[gasche]

I often rely on type feedback from my editor to navigate APIs. For PPrint this does not work well, due to the large number of combinators that take a long list of document arguments in an order that I never remember well. (I touch my pretty-printers rarely, so most of my PPrint hacking time is spent without the API in active memory.)

The most egregious example of this issue is PPrint.surround_separate_map, which I use regularly:

int ->
int ->
PPrint.document ->
PPrint.document ->
PPrint.document ->
PPrint.document -> ('a -> PPrint.document) -> 'a list -> PPrint.document

Quick, can you tell what is supposed to be the order of the four document arguments? I know that one of them is the "begin" document, one is the "end" document and one is the middle separator (presumably their order is begin, sep, end), I'm not completely sure what is the fourth one and where it is placed (maybe in first position?).

(I also don't really remember what the two int are for, but I know that I use 2 0 all the time so presumably the first is indentation.)

We could improve on this with labels, which would make the types more self-discoverable. For example:

int ->
int ->
leftright:PPrint.document ->
left:PPrint.document ->
sep:PPrint.document ->
right:PPrint.document ->
('a -> PPrint.document) -> 'a list -> PPrint.document

(This is deviating from the opening and closing terminology used in the documentation, which is better but also longer and does not read very well in openingclosing:document form.)