Search code, repositories, users, issues, pull requests...

Member

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.

Member

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?

Member

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.

Member

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

Contributor

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

Member

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

Contributor

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.

Member

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

Member

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.

Contributor

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.

Member

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

Contributor

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."

Member

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. 😄

Member

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."

It isn't invalid. People should not rely on this. Doing this would change the semantics of this de-structuring from just being a sugar for the dev to something that is important and that API dev must take into account. That would be a major change.

And that doesn't even take into account the useless information for the reader:

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.

Contributor

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.

That's a decision for the doc author to make, not rustdoc. Rustdoc's role is to provide a powerful, predictable tool. The doc author's role is to structure their code so that it provides useful information when rendered by rustdoc.

Here's an analogy: the names of function parameters are not used by the caller. But we include them in rustdoc output because they are useful in giving a hint about what that parameter will do. Since doc authors know the parameter names become part of the public documentation, they don't name parameters supercalifragilisticexpialidocious, they name them something useful like user. Similarly, a doc author can choose to use, or not use, a destructuring in their public API function signatures.

Member

I understand your point, but don't agree with all of it (and also don't completely agree with your analogy as you're mixing two different things). As soon as a destructured parameter is using a private field, then it doesn't provide useful information to the reader. So unless document-private is used, I think it shouldn't be displayed.

For me rustdoc has two different kind of usage:

generating docs for developers working on the crate (so with document-private)
generating docs for developers using the crate

Member

This could be even a security/logic issue. Example, a dev write this:

pub struct Struct {
    pub bar: u8,
    pub security_bit: u8
}

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

But than change it to:

pub struct Struct {
    pub bar: u8,
    pub security_bit: u8
}

pub fn func(Struct { bar, security_bit }: Struct) {}

Someone looking at the first version realize that security_bit doesn't matter but than the dev change it to the second code where it now matter. Nothing as changed from the API definition, but if rustdoc decided to show it would be relevant despite being a implementation detail.

conradludgate

ContributorAuthor

Regarding the private fields, I raised an issue a year ago showing that public functions can return 'private' types. rustdoc includes the type name in that return position, just it doesn't include any link to documentation for that type. Whether a function argument destructuring contains private fields or not I think is irrelevant.

I also don't know what kind of security problems it would cause since the source code is all publicly available anyhow.

The main reason I raised this issue was that I felt that without a proper name, function arguments can be very difficult to understand. __arg0 or _ doesn't help. Path(user_id): Path or user_id: Path would help a lot more in comparison.

Member

Regarding the private fields, I raised an issue a year ago showing that public functions can return 'private' types. rustdoc includes the type name in that return position, just it doesn't include any link to documentation for that type. Whether a function argument destructuring contains private fields or not I think is irrelevant.

I disagree showing private would not be helpful and would just add more distraction.
Concerning your example with Self as the return type, I agree that only showing Self without any other direct indication is not very helpful; rustdoc should maybe add a link to the impl<L> Router<L> part, but that's another issue.

I also don't know what kind of security problems it would cause since the source code is all publicly available anyhow.

Imaging that func does a manipulation between bar and security_bit, if security_bit was not set properly because when the programmer watch the function definition he saw that if wasn't used, it could lead to unwanted manipulation.

The main reason I raised this issue was that I felt that without a proper name, function arguments can be very difficult to understand. __arg0 or _ doesn't help. Path(user_id): Path or user_id: Path would help a lot more in comparison.

I think we all agree on this and we're trying to find the best solution for it.

As my final words on this issue I agree with @GuillaumeGomez: "So unless document-private is used, I think it shouldn't be displayed." and I don't know what should be displayed in the non document-private case.