search

rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
97.98k stars 12.68k forks source link

`rustdoc` lint to flag potential intra-doc links #131510

Open ojeda opened 2 weeks ago

ojeda commented 2 weeks ago

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:

/// Flags passed to `XArray::new` to configure the `XArray`.
/// Flags passed to [`XArray::new`] to configure the [`XArray`].
/// Converts the whole CString to lowercase.
/// Converts the whole [`CString`] to lowercase.

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 or MY_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 called run.

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

fmease commented 2 weeks ago

cc https://github.com/rust-lang/rust/issues/130126#issuecomment-2337193692 (last paragraph)

ojeda commented 2 weeks ago

@fmease Thanks for taking a look! If it ends up being expensive (even as allow-by-default), then perhaps it can be run only as an opt-in flag. I think there is value in this even if it doesn't run by default.