rustdoc
lint to flag potential intra-doc links
#131510
Labels
A-intra-doc-links
Area: Intra-doc links, the ability to link to items in docs by name
A-lints
Area: Lints (warnings about flaws in source code) such as unused_mut.
A-rust-for-linux
Relevant for the Rust-for-Linux project
C-feature-request
Category: A feature request, i.e: not implemented / a PR.
T-rustdoc
Relevant to the rustdoc team, which will review and decide on the PR/issue.
One of the common review comments in the Linux kernel is that there is a missed intra-doc link. It would be nice to have a lint (or two) to flag these cases automatically. In addition, such a lint would help new Rust developers become aware of what intra-doc links are.
There are two cases: the potential intra-doc link has backticks already, or it does not even have backticks (i.e. it was not even formatted properly using Markdown). Examples taken from LKML reviews:
Both cases will probably have false positives and thus projects may want to trigger them as an opt-in build mode (e.g. in the kernel we may run with a bigger set of warnings enabled to spot potential cleanups).
Due to the false positives, it may make sense to allow projects to customize what kind of "kinds" of entities to run it for, especially for the no-backticks case. For instance, for types or constants with multi-word names in projects following the usual naming conventions (e.g.
MyType
orMY_CONSTANT
), false positives may be unlikely. If someone has written "Returns MyType", then it is likely the lint applies; however, if they wrote "This item may run something" it is likely they didn't mean to link to a function calledrun
.Additionally, users may want to run the no-backtick lint even if they do not want to actually add intra-doc links, since it could spot missing backticks (i.e. bad formatting) with less false positives (since the compiler has more information). Clippy has a related lint,
doc_markdown
, which helps identifying missing backticks.These lints could be part of Clippy, but
rustdoc
already knows what could be an intra-doc link or not.Cc @GuillaumeGomez
@rustbot label T-rustdoc
@rustbot label A-intra-doc-links
@rustbot label A-rust-for-linux
The text was updated successfully, but these errors were encountered: