Docs.rs outputs silly signature of function when struct pattern matching involves

tools and infrastructure
1

My function signature in source code:

pub fn inwelling( Opts{ watch_manifest, watch_rs_files, dump_rs_paths }: Opts ) -> Inwelling;

And cargo doc outputs the same as above. But when crate inwelling has been published, the signature showed in docs.rs is:

pub fn inwelling(
    Opts { watch_manifest: watch_manifest, watch_rs_files: watch_rs_files, dump_rs_paths: dump_rs_paths }: Opts
) -> Inwelling;

I do not understand why it unnecessarily repeats field names of Opts. I known this will not lead to compile error, but, seems verbose.

Is it a bug or feature?

2

Docs.rs uses the latest nightly compiler, it seems likely this is a bug in that version of rustdoc; could you check if it happens locally on the nightly toolchain and open an issue in GitHub - rust-lang/rust: Empowering everyone to build reliable and efficient software. ?

3

This might be a dumb question, but should rustdoc show the destructuring? That seems like an implementation detail. From a public API standpoint the function's signature is pub fn inwelling(_: Opts) -> Inwelling. Is there any particular reason to reveal that the implementation destructures the struct?

3 Likes
4

Docs typically reveal the names of arguments, which are equally an implementation detail.

5

The argument names may also be self-documenting, so they shouldn't necessarily be hidden.

2 Likes
6

It definitely is an interesting trade-off. I think the last time this was discussed the leading idea was that rustdoc should show the pattern names if they differ from the struct field names, but showing struct field names when they don't differ is redundant.

Swift, a language with APIs built on function names, differentiates between the "caller" label for an argument and the "callee" label. The simple example is sendMessage(from:to:), though the callee side sendMessage(sender:receiver:) is fine enough for docs (and the former is just nicer for explicit labeling).

In-signature pattern destructuring is a place where the "caller" label and the "callee" label differ greatly, though. With full power manual documentation, I think I'd tell the caller fn inwelling( opts: Opts ) -> Inwelling as the signature. Maybe adding a rustdoc attribute to set the parameter name shown in documentation could be useful (and IDE argument name toasts could use it as well).

2 Likes
7

A while ago in a related discussion on r/rust, it occurred to me that Rust also supports giving "documenting" names to destructuring parameters, in the form of @ bindings. Well, the nightly Rust does, anyway. Rustdoc also only displays the name of the binding rather than the whole pattern, which is the desired behavior.

8

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.