convention for labeled arguments

[woeps]

I started looking at Core__Array.resi and found inconsistencies regarding the usage of labeled arguments. Afaik, this is also true in other modules.

When should labeled arguments be used?
A convention should be found to provide a consistent api surface.

---

Examples from Core__Array.resi

copyWithin

all labeled arguments but the one being operared on:

external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin"

fillInPlace

usage of labeled and non-labeled arguments within a single function:

@send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"

pushMany

no usage of any labeled arguments:

@variadic @send external pushMany: (array<'a>, array<'a>) => unit = "push"

[cknitt]

AFAIK there is currently no explicit convention, but looking at the bindings my understanding is the following: Only use labeled arguments in case it is unclear/not obvious from the type signature which parameter is which.

• Because the bindings follow the t-first convention, it is clear in the case of two parameters (like for Array.pushMany) that the first one is the object that the method is invoked on and the second one is the method argument. So there is no room for misunderstanding which is which and labeled arguments are not necessary.
• Even if there are more arguments, but of different types, there is little danger that they might be confused.
• However, if there are more arguments and two of them have the same type, as in Array.fillInPlace, it will be helpful to clearly indicate which is which, and so labeled arguments are used.

[zth]

Yes, what @cknitt says. There's no 100% consistent convention here, because we don't think that would yield the best result.

And to echo what has already been said, t-first means the first argument should be unlabelled.

Short term, we rely on:

• Signature help in the editor tooling to help with what type you're currently supposed to input
• Docstrings in the editor tooling to explain what the parameters are

Mid to long term, we want to be able to have docstrings on arguments too (can't do it with our AST today), which then would mean that docstrings explaining each individual argument could be show contextually on hover and in signature help. We'll need to make that possible first though.

[zth]

I hope that clarifies it. Feel free to reopen if not.