Rustdoc lint allows, in-situ

Currently, the only way to suppress lints from rustdocs is to use a #[allow] in the surrounding Rust code.

This is distressingly un-granular. For a long doc comment, the allow suppresses all iterations of the lint for the whole comment. For a crate- or module-level comments, it is necessary to apply the #[allow] to the whole module including all of its contents (ie, allowing the lint for all doc comments for all contained items).

I think it would be good if there was a way to be more specific. I suggest that we could use HTML Processing Instructions. I'm not sure of the precise syntax, but something like <?rustdoc allow(...)> maybe.

2 Likes

Currently, the only way to suppress lints from rustdocs is to use a #[allow] in the surrounding Rust code.

I'm not entirely sure what surrounding code and lints your comment refers to but there seems to be at least some granularity. Maybe you could give an example? Documentation is just a special form of attributes; you can mix attributes in arbitrary order. This implies you can #[allow] a lint on a specific lint on a single item only. You can even insert the allow in between documentation code lines and extra non-doc comments if that clarifies your intent at the code level:

/// Mentions [`MissingItem`].
pub fn but_it_applies_here() {}

/// This is a comment mentioning [`MissingItem`].
#[allow(rustdoc::broken_intra_doc_links)]
/// And it continues here and never warns about the item.
pub fn test() { }
warning: unresolved link to `MissingItem`
 --> src/lib.rs:1:16
  |
1 | /// Mentions [`MissingItem`].
  |                ^^^^^^^^^^^ no item named `MissingItem` in scope
  |
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
  = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

warning: `testing` (lib doc) generated 1 warning

Ah. TIL about the per-line allows. But, I've done #![doc=include_str!("../README.md")] and the things rustdoc is complaining about are in the README.md. I don't think I can escape back to the Rust context from there (and it would be quite a hazard if I coiuld).

1 Like