Is there (should there be) a library doc style guide?

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?

3 Likes

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.


Another related question is how more complex inline-code expressions are to be handled. (“more complex” ≈ pretty much everything that has more than one token, e.g. Box<T> but in particular everything that contains at least two different types that could be linked, e.g. Pin<Box<T>>)

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.

The style guide is at rfcs/1574-more-api-documentation-conventions.md at master · rust-lang/rfcs · GitHub. There's even a section that recommends linking everything. That was written before intra-doc-links, so use intra-doc-links instead.

Additional Documentation guidelines are at Documentation - Rust API Guidelines.

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.

2 Likes

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).

1 Like