Function argument names are exposed

[infinisil]

The file

{
  /* Some description */
  f = x: x;
}

gets rendered as

Some description

`x`

: Function argument

Note how x gets rendered, even though that name is internal^1 to the function, it's not part of the functions API.

nixdoc should either not render that name at all or require the code to give it an explicit name.

[asymmetric]

What should the CommonMark look like then? Are you saying it should somehow say "Function argument" without mentioning it's called x? What would be a better placeholder?

In general, I'm not sure this poses a real problem, but maybe I'm missing something!

[infinisil]

Here's a proposal:

Render

{
  /* Some description */
  f = x: x;
}

as just

Some description

Only render arguments if they're explicitly documented, and don't use their names:

{
  /* Some description */
  f =
    # Function arg
    x: x;
}

renders as

Some description

Argument 1

: Function arg

Though we should also keep RFC 145 on doc comments in mind.

[iFreilicht]

I disagree. While technically, yes, the names of the arguments is not part of the interface of the function, they are still useful information for a human and help to identify the arguments and their purpose. It seems counterproductive to elide this useful information just for the sake of being "technically more correct".

[hsjobeki]

Since i added support for RFC145 this can be closed i guess? This is only an issue with the old behavior. If you want to avoid this issue simply migrate your comments to use /** */ syntax. This wont expose function argument names.

[infinisil]

Yup sounds good!