Intra-doc links for keywords

I see in this issue about intra-doc links for true and false that rustdoc doesn't currently support intra-doc links for keywords in general, and it seems several folks were pretty strongly against it. I'm curious what the rationale is?

In working on the API docs for Neon, which is a library that specifically tries to cater to new Rust programmers, and I'd like to be able to link to the move keyword in the standard API docs to explain common usage patterns like spawning threads with a move closure.

I can of course hard-code the link to the official URL, but not having support from the tooling the way primitive types do makes me wonder if I'm doing something that's considered bad practice. Our docs already use intra-doc links for things like pointer and reference, so I was surprised when move didn't work.

Looking forward to hearing folks' thoughts, thanks!

Some prior discussion: Discord

Also, looking back at this I think allowing true and false was not a great decision, it seems like a weird special case especially since it generates a link to bool instead.

true and false can be rationalised as linking to the variants of enum bool { true, false }. Similarly pointer and reference make sense as links to the otherwise unnameable type constructors *const _ and &_ respectively (I'm slightly surprised that with the support for generic parameters [`*const T`] and similar doesn't work now). Those are all "types" or "values" that should have pages in the library documentation.

move and other keywords feel different. They are part of the language, so if there were a way to link to them I would expect those links to go to the language reference page, which is a rather large difference from how the rest of intra-doc links work.

3 Likes