Duplicate entries in side bar in std docs for pointer

[VorpalBlade]

Location

https://doc.rust-lang.org/std/primitive.pointer.html

Summary

Most of the methods are listed twice, but the two entries take you to the same documentation entry:

[hanna-kruppe]

https://doc.rust-lang.org/std/primitive.pointer.html#method.add is the add method on *const T, while https://doc.rust-lang.org/std/primitive.pointer.html#method.add-1 is the add method on *mut T.

[VorpalBlade]

Both say self as the receiver type, and normally Rust does not have function overloading. For https://doc.rust-lang.org/std/primitive.pointer.html#method.is_aligned-1 for example the signature listed in rustdoc is identical. So you can't even tell which is which.

Const and mut pointers should be split into two separate documentation pages.

[VorpalBlade]

The other way to make this page not confusing would to have rustdoc explicitly list what the self type is for each entry, but that seems like it would be relevant only to pointer docs. As that is the only page (that I know of) that mushes together multiple types into one confusing mess.

[hanna-kruppe]

Pointers are the worst offenders but it’s not exclusive to them, e.g., Box has three downcast methods (plus ref/mut/unchecked variants) from three distinct inherent impls. Result and Option have two each of copied and cloned. etc. etc.

[VorpalBlade]

Hm, indeed. For box downcast, the impl block in question happens to be listed just above the method in the main docs page, but that is just by chance. You can however still tell them apart even without that as their return types differ.

However, this is a worse issue when the impl block is nowhere to be seen, and the signatures do not contain any info to tell things apart (such as pointer is_aligned as mentioned above).

I'm not sure what the proper fix for this would be, but the current state is not great, and is likely to trip up people who don't know about this particular detail. Some thoughts for how to improve this:

• Should rustdoc group by impl in the side bar? I imagine that would often be less than ideal though, when there isn't a lot of duplication (e.g. some methods only exist if T: SomeTrait). There is an argument for having the list be alphabetical in most cases.
• Perhaps we could make the impl block more obvious in the main block. For example we could maybe have the current impl block sticky to the top of the screen? Though impl block with lots of where clauses can get unwieldy and eat too much screen real-estate.
• Perhaps (since the above point would be an issue) we could make something that is of fixed size / collapsed & expandable with a ....

[lolbinarycat]

Another option would be adding a tooltip on self that shows what the type is, although that doesn't help on mobile as much, and may have poor discoverability.

[lolbinarycat]

Alternatively, if we add the ability to normalize type aliases, we could expand that to normalizing self parameters to show their actual type, probably configurable through an attribute.

[VorpalBlade]

Another option would be adding a tooltip on self that shows what the type is, although that doesn't help on mobile as much, and may have poor discoverability.

It also doesn't help when the associated function doesn't take self. However it isn't a bad idea, and you can make it work on mobile by making a dashed understore link that opens the tool tip on click. I have seen this used for things like abbreviation definitions, but I can't remember where.