Clippy lint · Suspicious · checked with Clippy 0.1.99

clippy::doc_suspicious_footnotes: looks like a footnote ref, but has no matching footnote

What it meansDetects syntax that looks like a footnote reference. Rustdoc footnotes are compatible with GitHub-Flavored Markdown (GFM). GFM does not parse a footnote reference unless its definition also exists. This lint checks for footnote references with missing definitions, unless it thinks you’re writing a regex. It is in the suspicious group and warns by default.

What you see

warning: looks like a footnote ref, but has no matching footnote
 --> main.rs:3:27
  |
3 | /// This is not a footnote[^1], because no definition exists.
  |                           ^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/stable/index.html#doc_suspicious_footnotes
  = note: `#[warn(clippy::doc_suspicious_footnotes)]` on by default
help: add footnote definition
  |
3 ~ /// This is not a footnote[^1], because no definition exists.
4 + ///
5 + /// [^1]: <!-- description -->
  |

Real output of Clippy 0.1.99 (Rust 1.99) on the example below. Names and line numbers in yours will differ.

Does it matter?

This probably means that a footnote was meant to exist, but was not written.

Code that is most likely wrong or useless. Warns by default.

How to fix it

Clippy does not fix this one automatically (its suggestion may change behaviour, so it only shows it). Change the code by hand:

Flagged

/// This is not a footnote[^1], because no definition exists.
fn my_fn() {}

Write this instead

/// This is a footnote[^1].
///
/// [^1]: defined here
fn my_fn() {}

Turn it off, or on

Allow it where it does not fit your code, as narrowly as you can:

On one item

#[allow(clippy::doc_suspicious_footnotes)]
fn my_function() { /* ... */ }

Whole crate (Cargo.toml)

[lints.clippy]
doc_suspicious_footnotes = "allow"

One run

cargo clippy -- -A clippy::doc-suspicious-footnotes

The [lints] table needs Rust 1.74 or newer. In a workspace, put it under [workspace.lints.clippy] and add [lints] workspace = true to each member.

Suspiciousgroup

warndefault level

nofixed by cargo clippy --fix

1.89.0added in Rust

Clippy's own documentation

What it does

Detects syntax that looks like a footnote reference.

Rustdoc footnotes are compatible with GitHub-Flavored Markdown (GFM). GFM does not parse a footnote reference unless its definition also exists. This lint checks for footnote references with missing definitions, unless it thinks you’re writing a regex.

Why is this bad?

This probably means that a footnote was meant to exist, but was not written.

Example

/// This is not a footnote[^1], because no definition exists.
fn my_fn() {}

Use instead:

/// This is a footnote[^1].
///
/// [^1]: defined here
fn my_fn() {}

From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.

Up next

Also worth your time

Did this answer your question?