Fix legacy_const_generic doc arguments display

[GuillaumeGomez]

Fixes #83167.

cc @Amanieu

[rust-highfive]

r? @ollie27

(rust-highfive has picked a reviewer for you, use r? to override)

[GuillaumeGomez]

r? @jyn514

[jyn514]

I don't really have time to review this properly ... @Amanieu @Mark-Simulacrum does this look like about the transformation you expect?

[GuillaumeGomez]

Updated.

[Mark-Simulacrum]

I think some indication that the arguments must be const should be given -- there's no canonical Rust syntax for this yet, though.

[GuillaumeGomez]

@Mark-Simulacrum So what should be changed here exactly? If the syntax isn't present yet, I'm not sure what I can do but if you have suggestions, please go ahead. :)

[Mark-Simulacrum]

There's some discussion starting at #83167 (comment) of options for rendering.

Can you provide a screenshot of what one of these functions looks like before/after this PR? That might help with discussion since currently reading the code seems necessary.

[GuillaumeGomez]

Sure, here you go.

Current version:

With this PR (no more generics):

I also rebased on master.

[Mark-Simulacrum]

Yeah, ok, that matches what I thought.

I would suggest adding const before the argument name -- that may be a useful signal that the argument is special. Users can't currently create such an argument themselves, which is unfortunate, but feels a little unavoidable to me at this time.

I think that would move us in the right direction, but I'm not sure it's enough, particularly for call-sites which are using the regular const-generic syntax (i.e., with turbofish), which will look like they're omitting valid options. One benefit to us might be that I think all such "weird" functions are currently only leaf functions (i.e., not trait methods, etc) so we may be able to just duplicate the signature twice with an "or" in between or something like that, though it's probably painful to do in rustdoc's current design from what I recall.

Overall, I think it's important to show users both styles if neither style issues deprecation warnings (which I believe is currently the case), and important to signal the need for the argument to be const. It may be worth nominating for libs-api to discuss whether there is a preferred syntax for calling these functions, and whether we wish to deprecate one of the forms; that would alleviate the concern over users encountering both syntaxes in the wild -- at least over time.

[GuillaumeGomez]

Let's ping them then. cc @rust-lang/libs-api

[Amanieu]

I personally think that just having:

pub fn foo(x: usize, const Y: usize, z: usize);

is enough since that is the form used by the vendor APIs. I don't think we need to expose the desugared generic form of the function in the documentation.

[Mark-Simulacrum]

I largely agree, with a possible caveat of a single paragraph at the root (core::arch module docs) explaining this, if it doesn't exist yet. I think it would definitely be an improvement on the status quo.

[GuillaumeGomez]

It now looks like this:

[Amanieu]

LGTM

[GuillaumeGomez]

@bors: r=Amanieu

[bors]

📌 Commit 5c75a48 has been approved by Amanieu