Argument names in Roc documentation

[bhansconnect]

What is the plan around argument names in Roc standard library docs?

For example, looking at List.reserve, it will "Enlarge the list for at least capacity additional elements". The function signiture is [reserve](https://www.roc-lang.org/builtins/List#reserve) : List a, Nat -> List a.

This is essentially implicitly naming the second argument "capacity". This may be confusing in some situation with more arguments. So two main questions:

1. Can/should we add some sort of function parameter name documentation to the standard library docs?
2. If we aren't going to add name information, how should we refer to each argument/what would be better wording?

[ayazhafiz]

I think adding parameter name documentation is a really good idea, but I don't have the greatest sense of the right way to do it.

One nice property of the docs today is that you can copy and paste a type signature into Roc code; that is, the signature docs are pure Roc code.

If we care about preserving that property, I think there are a few options here.

1. We could add hover tooltips over the types of parameters to show their displayed names. That is, something like this, but prettier:

I think this solution has some downsides. One is that you can't see all of the parameter names at once, you have to hover over each, which can make reading the docs harder. The second is that this interactive aspect could be hard on mobile, and I don't think you necessarily want that much interactivity to read docs.

2. Add in-line parameter names that are smaller and not selectable. That is, something like this

And when you select the type signature, the parameter names will not be selectable. That way you can still copy-paste the type signature. I like this option more but it has the downside that it's no longer pure Roc syntax. OTOH I don't think it's likely anyone will think this is proper syntax.

3. There are other options like having two lines,

which doesn't look too bad in this example, but wouldn't play well with multi-line type signatures.

From the technical side we'd also need to figure out how to implement these kinds of docs for signatures missing implementations, like straight-to-lowlevel functions in the stdlib. I guess we could just hard-code those.

[lukewilliamboswell]

Could we have both at the same time? Maybe some kind of interaction could work. Im thinking visually it would provide more information and then on hover it changes to the copy'able pure version. Or maybe there is a "copy to clipboard" button that copies the Roc code?