Stream: ideas

Topic: Add parameter names to docs

Jonathan (Sep 22 2026 at 10:09):

Unsure if there's an existing reason for/against this, but currently the docs do not add any parameter names and only show the types, so I often go to the source instead of the docs for clarity. See below for an example from basic-cli (that I find confusing):

map_value : (a -> b -> [
    Ok(
        c,
    ),
    Err(
        d,
    ),
]), (c -> e) -> a -> b -> [
    Ok(
        e,
    ),
    Err(
        d,
    ),
]

I believe that structural typing, moreso than nominal, exacerbates the need for clear docs. One possible improvement I see is if the function signature renders with inline parameter names, something like this with the names in grey italics:

map_value : (
*gen_decode* a -> b -> [
    Ok(
        c,
    ),
    Err(
        d,
    ),
]),
*mapper* (c -> e)
->
a -> b -> [
    Ok(
        e,
    ),
    Err(
        d,
    ),
]

Which reveals it takes two args, and returns a curried function (There's also still a bug here in that the returned function is not grouped in parens). It also shows that there is perhaps some overuse of newlines and trailing commas that imo makes it hard to read (also adding in the missing parens):

map_value : (
*gen_decode* (a -> (b -> [Ok(c), Err(d)]))),
*mapper* (c -> e)
-> (a -> (b -> [Ok(e), Err(d)]))

In this form, I believe it is much easier to see

• That there are two arguments
• That the first argument is a standard decoder shape for the module
• That the second argument maps over the result of the decoder.

This is mostly clear from the function name already, but I think it demonstrates the discrepancy.

Of course, this example isn't helped by the fact that it is generated, and so a and b could be col and stmt, and the union could be Try.

Anyway, I'm not proposing that my suggestion is the way to go, just that I find the current docs quite confusing, especially trying to match up the parens in my head or figure out how the arguments are grouped and nested.

Anton (Sep 22 2026 at 11:07):

Yeah, we should add argument names. Whoever takes this can play around with it and see what looks good.

Anton (Sep 22 2026 at 11:07):

I also agree on overuse of newlines

Anton (Sep 22 2026 at 11:08):

I will leave some time for additional input and make issues after.

Anton (Sep 22 2026 at 17:58):

#11591

Anton (Sep 22 2026 at 18:03):

#11592

Richard Feldman (Sep 22 2026 at 22:54):

I actually don't want to add parameter names to docs

Richard Feldman (Sep 22 2026 at 22:54):

I think it's a problem if the type is not understandable on its own

Richard Feldman (Sep 22 2026 at 22:55):

and generally the better fix is to try to improve the type rather than to bring in the extra information of the parameter names

Dan G Knutson (Sep 22 2026 at 23:56):

What if we encouraged using named aliases in docs, and modified the default formatting to use some heuristic for grouping arguments together on a line where possible?

So like, this example:
https://roc-lang.github.io/basic-cli/0.21.0-rc4/Sqlite/#Sqlite.Stmt.query!

query! : Stmt, List(
    Binding,
), (List(
    Str,
) -> SqliteStmt -> Try(
    ok,
    [
        SqliteErr(
            ErrCode,
            Str,
        ),
        ..[
            NoRowsReturned,
            TooManyRowsReturned,
        ],
    ],
)) -> Try(
    ok,
    [
        SqliteErr(
            ErrCode,
            Str,
        ),
        ..[
            NoRowsReturned,
            TooManyRowsReturned,
        ],
    ],
)

could become:

    QueryErr : [
        SqliteErr(ErrCode, Str),
        ..[NoRowsReturned, TooManyRowsReturned],
    ]

    query! :
        Stmt,
        List(Binding),
        (List(Str) -> SqliteStmt -> Try(ok, QueryErr))
        -> Try(ok, QueryErr)

Dan G Knutson (Sep 22 2026 at 23:59):

Also:

• fixing an incorrect error union could be an LSP action, which would make that easier to maintain (like an add variant action or something)
• I do kind of want roc fmt to let me do that -> ReturnType line thing

Richard Feldman (Sep 23 2026 at 00:41):

yeah the formatting on the current docs looks bad, but also yeah - with an alias it would look much better :smile:

Richard Feldman (Sep 23 2026 at 00:42):

also the formatter should fix this:

    [
        SqliteErr(
            ErrCode,
            Str,
        ),
        ..[
            NoRowsReturned,
            TooManyRowsReturned,
        ],
    ],

that is just a bizarrely confusing way to write it

Richard Feldman (Sep 23 2026 at 00:42):

should be flattened:

    [
        SqliteErr(
            ErrCode,
            Str,
        ),
        NoRowsReturned,
        TooManyRowsReturned,
    ],

Jonathan (Sep 23 2026 at 08:55):

Richard Feldman said:

and generally the better fix is to try to improve the type rather than to bring in the extra information of the parameter names

Yeh that makes sense; much of the improvement I see comes from better newlines and indentation, if not from aliases.

Last updated: Sep 24 2026 at 15:59 UTC