rustdoc: some trait methods appear as "hidden undocumented items"

[eminence]

Using the Clone impl for Vec as an example, here's what the latest stable docs look like:

Whereas the latest nightly docs look like this:

This issue was mentioned #56073 but I believe this issue is important enough to pull into its own issue. I also think this issue is a candidate for a "regression-from-stable-to-nightly" flag.

[GuillaumeGomez]

What's the problem with that? Those items don't have documentation and are therefore using the one from the trait definition. They are undocumented, that's a fact. What do you suggest we should do instead?

[eminence]

In my specific example with the Clone trait, I believe the old behavior produces good results because the trait method documentation is written in such a way to make sense for all types that derive Clone. So my initial suggesting would be to switch back to the old behavior of taking the documentation from the trait if the impl does not provide one.

However, I can imagine that this isn't true for all traits, and there may be examples where applying the trait documentation to the implementation might not make sense. Do you know if there are specific examples of this? Was this related to why this behavior was changed?

The root of my complaint is that categorizing important methods like clone() as "hidden undocumented" is confusing. To me a "hidden undocumented" method is one that should be avoided (my thought process is something like: "If the authors wanted me to use this method, they would have documented it and unhidden it")

I suppose one way to resolve my complaint would be to manually duplicate the trait documentation onto the impls, but this seems tedious and error-prone 😃

[QuietMisdreavus]

Hiding the methods was deliberate. The idea is that when looking at a type that implements a bunch of standard traits but hadn't put special notes on any of them, the only important thing the user needs to know is that the trait is implemented. Seeing your comment, i bet the verbiage could be improved, but the feature itself was deliberately added to try to keep the page length from getting excessive.

[QuietMisdreavus]

I suppose one way to resolve my complaint would be to manually duplicate the trait documentation onto the impls, but this seems tedious and error-prone 😃

If you expand the "undocumented" items, rustdoc already does that for you. The impls are undocumented, so we copy over the trait's documentation. Again, the idea is that if you see the same trait everywhere, and a given implementation doesn't add any extra documentation, just knowing it's there is enough.

The behavior was added in #54162 if you want to read over that thread.

[eminence]

Thanks for sharing the relevant issue number. I am certainly sympathetic to the issue of page length. I think that collapsing the trait section by default is a good step, but I still maintain that classifying these methods as "hidden undocumented" is confusing and misleading (especially to new users who may not be familiar with these standard traits).

Are you open to suggestions on how to improve this? I think one possibility would be to automatically expand the method docs when expanding the trait (since currently expanding the trait shows nothing of value).

[birktj]

I think this would be better if the default impls also appeared under the "undocumented" items. Currently it looks sort of strange when a bunch of default impls are shown but the most important items are hidden.

[nstoddard]

I ran into this issue when reading the docs for the cgmath crate. On the Vector3 docs, for the MetricSpace impl, the distance2 method is hidden by default, which initially makes it look like it doesn't exist. The same problem occurs for the InnerSpace impl.

I see how this feature is helpful for traits like Clone for which there's nothing interesting about the implementation other than the fact that it's implemented, but for many other traits, it often hides important methods. Would it be possible to restrict this feature to traits like Clone?

[TheZoq2]

The same issue is present in the embedded_hal world. Nearly all the functions from the embedded_hal crate are hidden in the stm32f1xx_hal docs.

It seems weird to always hide trait impls as there could be some very useful functions in there, as is the case in stm32f1xx_hal

[GuillaumeGomez]

@TheZoq2: You don't look at the problem as a whole: in this case they could all be expanded, it wouldn't change much. But in some cases where a type has a lot of trait implementations, it becomes very complicated to read. The current orientation would be to reformulate the sentence, not to re-expand everything automatically.

[agrif]

Perhaps a trait could indicate at the definition point that its documentation should be expanded automatically? Like @nstoddard's suggestion. The issue seems to be that there are two types of traits:

1. Traits like Clone, where you are likely to see it very often and already have an idea of what it provides. Hiding these traits reduces visual noise and makes it easier to get at more important info.

2. Traits like InnerSpace in cgmath, that most people will probably not see often enough to learn each of the 8 methods it provides. Especially for cgmath, hiding 'undocumented' traits by default makes it very hard to learn what methods a type like Vector3 even provides. If InnerSpace could opt-in to showing trait items and docs by default, that would be a pretty good compromise.

Whether this behavior should be opt-in or opt-out is a good question, though.

Edit: another possible solution, let the documentation for a given type 'promote' certain traits it implements, to be shown expanded directly under the inherent impl. Vector3 could promote InnerSpace, etc, and improve its documentation considerably.

[m-ou-se]

Not all undocumented items under impl blocks are hidden by 'Show undocumented items':

For example: https://doc.rust-lang.org/std/cmp/trait.PartialEq.html#implementors

Here, some of the ne are shown, and some are not, even though all are undocumented:

Is this an unrelated bug?

[RalfJung]

In fact sometimes this leads to only showing deprecated items per default while not showing the actual public API:

• Go to https://doc.rust-lang.org/nightly/std/process/struct.Command.html
• Scroll down to the "impl CommandExt for Command" (there's two of them but that is not the issue).
• Click [+] for the first of them

Two sub-items appear: "Show hidden undocumented items" and before_exec. That is very strange, since the items that are shown when unfolding the "undocumented" part are not at all undocumented -- in fact, they are the main API surface while before_exec is deprecated!

Similarly, for the second "impl CommandExt for Command" (for Windows), the only item is also folded as "hidden undocumented".

So there is certainly a bug here where some methods are hidden and others are not, for no apparent reason. But beyond that, I think hiding them at all is a bug in the case noted above: Note that I already clicked on the [+] to even see the trait methods! Then it shows nothing except for some scary note about undocumented items, and now I have to click a second time and ignore the factually incorrect message to see the documentation I am looking for. How can this be intended behavior?

I understand not unfold trait impls per default as there can be many of them, but do they really have to be hidden behind two clicks?

[phil-opp]

I think it would be more intuitive to also hide functions with default implementations when they're not overridden. Yes, they're technically documented since there is some documentation on the default implementation, but there is no "overridden" documentation inside the impl block.

Consider the following example on why the current behavior is confusing:

pub trait Foo {
    /// Do something
    fn do_something(&self);

    /// Do something twice
    fn do_something_twice(&self) {
        self.do_something(); self.do_something();
    }
}

pub struct Baz;

impl Foo for Baz {
    /// Do something special since this is a Baz instance and bla bla…
    fn do_something(&self) {
        println!("Foo");
    }
}

The generated docs look like this:

The current implementation shows the default method do_something_twice in the same way as the method do_something that has "overridden" documentation.

This leads to confusing docs, especially when no implementations contain "overridden" documentation:

pub struct Bar;

impl Foo for Bar {
    fn do_something(&self) {
        println!("Bar");
    }
}

Now do_something is hidden as "undocumented", but do_something_twice is still shown:

The user that sees this documentation doesn't know if do_something_twice does something special and thus has "overridden" documentation, or if it's just a simple default implementation.

[GuillaumeGomez]

@phil-opp Can you open a specific issue about this one please? (and ping me on it)