doc_markdown footnote identifier false positive #13183
Description
Summary
Clippy falsely raises the doc_markdown lint in Markdown footnote identifiers.
Secondarily, though not relevant if the root cause is fixed, the suggested fix is incorrect.
I personally prefer the use of more descriptive footnote identifiers as it makes refactoring/reorganising of docs much simpler, as opposed to using [^1] ... [^2] ... which can easily go out of order.
Lint Name
doc_markdown
Reproducer
//! Here's a footnote[^example_footnote_identifier] //! //! [^example_footnote_identifier]: This is merely an example. I saw this happen:
warning: item in documentation is missing backticks --> src/lib.rs:1:22 | 1 | //! Here's a footnote[^example_footnote_identifier] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown = note: `-W clippy::doc-markdown` implied by `-W clippy::pedantic` = help: to override `-W clippy::pedantic` add `#[allow(clippy::doc_markdown)]` help: try | 1 | //! Here's a footnote`[^example_footnote_identifi`er] | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Workaround
One workaround (and possible suggested fix) would be to change the use of snak_case into kebab-case:
//! Here's a footnote[^example-footnote-identifier] //! //! [^example-footnote-identifier]: This is merely an example. Version
rustc 1.79.0 (129f3b996 2024-06-10) binary: rustc commit-hash: 129f3b9964af4d4a709d1383930ade12dfe7c081 commit-date: 2024-06-10 host: aarch64-apple-darwin release: 1.79.0 LLVM version: 18.1.7