Documentation for Implemented Traits Confusing for Beginners

[zwhitchcox]

I posted in Reddit about a method that seemed to be missing in the Range documentation, and it was explained to me that this method (map) came from a different trait called Iterator.

Most people seemed to know this, but when asked how I would find this information if I didn't know every method on every trait that Range implemented, no one seemed to have a good answer.

The first way was to expand all the information about all the traits. Only the "expand all" button doesn't really expand everything, but just what someone seems to have determined is important, which did not include the map method.

So, then the next step, which was to manually expand every single method of every single trait that was implemented for Range.

This brings us to my first point. The expand everything button should actually expand everything.

There should also be a search box that allows you to search for the methods the trait implements. You could practically get this for free, as the info seems to already be downloaded to the page. I can see no reason why a search feature would not be implemented, especially in light of the fact that you can't do a search on the page with Ctrl+F due to everything being hidden and no easy way to expand everything.

The second point is that there should only be methods that are actually implemented for the actual struct of the page I am on. If a struct doesn't implement a method of a trait that it implements, there is not reason for it to be on that page other than to confuse people.

I get the feeling that people have worked with Rust for so long that they know all this stuff by heart, but for a beginner, this is very confusing, and it also doesn't scale once people start implementing their own structs that people won't have memorized.

To be honest, this is almost enough to make me leave the language. I will probably just wait to learn it until proper documentation is implemented though. If I can't deterministically tell what method will do what, how am I supposed to use this language to code?

But think about how awesome it would be if you could just go a struct's documentation page and just scroll through and see every method implemented for the struct and only methods actually implemented?

[jyn514]

I agree with most of these points actually (Iterators are one of the most confusing things for beginners), but this is not the right place for this issue, docs.rs just hosts the docs. Could you open an issue at https://github.com/rust-lang/rust instead?

[pietroalbini]

Transferred the issue.

[the8472]

The second point is that there should only be methods that are actually implemented for the actual struct of the page I am on. If a struct doesn't implement a method of a trait that it implements, there is not reason for it to be on that page other than to confuse people.

Quite the opposite has been requested before. Sometimes people just want a list overview of available methods and their signatures on a struct and care less which trait impl or deref coercion they come from.

61190 #40273