Better pattern argument naming in rustdoc

[conradludgate]

I noticed with function pattern arguments that rustdoc makes some interesting choices regarding argument names.

For instance:

fn func(Foo(bar): Foo) {}

gets rustdoc'd into

fn func(__arg0: Foo) {}

(see
https://docs.rs/atuin-server/0.9.1/atuin_server/handlers/history/fn.calendar.html for a real life version)

It's hard to say what rustdoc should do in the general case, but there are some simple cases that could be improved.

For the single capture pattern, the argument could inherit the name. Eg, in the example above, it could be rendered as bar: Foo.

However, this single capture rule should maybe not apply if in a case like

fn func(Struct { bar, .. }: Struct) {}

Since bar might be a small subset of what the type is representing, and might be misleading (or implementation detail).

In the general case, the argument name could be a snake case version of the type name, if no conflicts. This is the best heuristic I can come up with for a sensible name

[GuillaumeGomez]

In such case, I think generating something like:

fn func(_: Foo) {}

would work out nicely enough.

[Urgau]

In such case, I think generating something like:

fn func(_: Foo) {}

would work out nicely enough.

Except that someone might think that because it's _ it doesn't matter and isn't used at all, which is certainly not the case.

[GuillaumeGomez]

I'm not sure that printing Foo(bar): or Struct { bar, .. }: would be better though. What useful information would it provide for the doc reader?

[Urgau]

I'm not sure that printing Foo(bar): or Struct { bar, .. }: would be better though. What useful information would it provide for the doc reader?

Agree, printing Foo(bar): or Struct { bar, .. }: wouldn't be useful either.
Maybe simply printing arg0 instead of __arg0 might already be better.

[GuillaumeGomez]

It's not great either... Any opinion on this @rust-lang/rustdoc?

[jsha]

Can we pass through exactly what was written in the source code by the author?

[GuillaumeGomez]

I suppose so, but once again: would this destructuring information be useful for the doc reader?

[jsha]

Yes. For instance, if a destructuring only cares about a single field of a big struct, it's useful for the caller to know that only that one field matters.

Also, passing through the original improves predictability. People's general mental model of what shows up in rustdoc is "the function signature as written, plus some hyperlinks and formatting." It's confusing to deviate from that.

[GuillaumeGomez]

This is a good point. My main worry was the complexification of the doc but I guess it's secondary.

[Urgau]

Yes. For instance, if a destructuring only cares about a single field of a big struct, it's useful for the caller to know that only that one field matters.

But that's a implementation detail not a promise. The field might be private and this would be even more confusing for the reader.

[jsha]

This is true - but I think it's more confusing (for both the author and the reader) for the documented function signature to be different from what's written in the code.

If the author wants to make sure users can't see the destructuring, they can put it inside the function. If the author does want users to see the destructuring, they can put it in the function signature. This approach gives both predictability and flexibility for the doc author.

[GuillaumeGomez]

But the problem about private fields remains though. And it's quite a big one.

[jsha]

If the function signature includes a destructuring that names a private field, we should go ahead and list that name, with a doc lint saying "this function signature exposes the name of a private field."

[GuillaumeGomez]

That seems like way too much useless information. Why would this be useful for the reader? For me it looks like explanations about what they're reading. It seems more confusing than useful.

I didn't expect this issue to be so complicated. 😄