While making a patch explaining "logic errors" better , I noticed an inconsistency -- there were two very similar pieces of text, one of which used `Cell` (unlinked) and one which used [`Cell`] (linked). Interested in this, I decided to write a (horrible) script to see which terms used references and which don't.
`true` is used linked 36 times and unlinked 210 times. `false` on the other hand is linked 8 times and unlinked 86 times. `Err` is also used about half-and-half linked and unlinked.
Often unlinked uses are inside the documentation for that type, for example, most (but not all) links to Box in the Box documentation aren't links.
In the long term it might be nice to have some kind of automatic linter which could detect inconsistencies like this, but for now, is there a general style guide for the library docs which talk about when and what to link?
Could you links the examples that are links? I couldnât find any at a glance.. Of course the module-level docs of std::boxed have links to Box. A hyperlink to the same page you are already on doesnât make any sense though, so the docs of Box or its associated items are not supposed to link to Box. Trait implementations are appearing on both the pages for Box and the respective trait, so I guess including hyperlinks there is okay again.
Sorry, I looked at the source, rather than what pages were generated from the source. As you say, there are some links in alloc::boxed - Rust has both Box as reference, and Box not as reference. I think in general more links are missing, than additional.
For example, std::ptr::NonNull - Rust and std::ptr::drop_in_place - Rust do not link to Rc or Arc, and there is some standard text about undefined behaviour which contains " For instance, Vec and Box ensure they never allocate more than", which does not link to Vec and Box.
I don't think this is explicitly written down, but I think the general style is to link the first occurrence of a term, but don't repeat the links on subsequent uses. If you find terms that have no links on a page, feel free to send a PR to add them. intra-doc-links have come a long way and it should be much easier now.
Consider creating intra-doc-links for any inline code snippet #75296 would get rid of the described problem, because non-links would automagically become links. However I argumented against this claiming that it would be "too magical" and it might be strange for documentation to render things the way the user did not explicitly intend. And if it was magic, some would like an option to turn it off, leading to more complexity.
As for having a resource with documentation guidelines, I'd love it! I think I've tried to find one such guide before with no success (although I may not have looked too much).