Repository navigation
Duplicate entries in side bar in std docs for pointer #142147
Description
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:
Activity
hanna-kruppe commentedon Jun 7, 2025
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 commentedon Jun 7, 2025
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 commentedon Jun 7, 2025
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 commentedon Jun 7, 2025
Pointers are the worst offenders but it’s not exclusive to them, e.g.,
Boxhas threedowncastmethods (plus ref/mut/unchecked variants) from three distinct inherent impls.ResultandOptionhave two each ofcopiedandcloned. etc. etc.VorpalBlade commentedon Jun 7, 2025
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_alignedas 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:
T: SomeTrait). There is an argument for having the list be alphabetical in most cases.....lolbinarycat commentedon Jun 9, 2025
Another option would be adding a tooltip on
selfthat shows what the type is, although that doesn't help on mobile as much, and may have poor discoverability.lolbinarycat commentedon Jun 9, 2025
Alternatively, if we add the ability to normalize type aliases, we could expand that to normalizing
selfparameters to show their actual type, probably configurable through an attribute.VorpalBlade commentedon Jun 9, 2025
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.
Rollup merge of rust-lang#162778 - lolbinarycat:rustdoc-sidebar-disam…
Rollup merge of rust-lang#162778 - lolbinarycat:rustdoc-sidebar-disam…
Rollup merge of rust-lang#162778 - lolbinarycat:rustdoc-sidebar-disam…
Rollup merge of rust-lang#162778 - lolbinarycat:rustdoc-sidebar-disam…
Unrolled build for #162778 in rollup 164418