Clippy lint · Suspicious · checked with Clippy 0.1.99

clippy::doc_nested_refdefs: link reference defined in list item

What it meansWarns if a link reference definition appears at the start of a list item or quote. It is in the suspicious group and warns by default.

What you see

warning: link reference defined in list item
 --> main.rs:3:7
  |
3 | //! - [link]: description
  |       ^^^^^^
  |
  = help: link definitions are not shown in rendered documentation
  = help: for further information visit https://rust-lang.github.io/rust-clippy/stable/index.html#doc_nested_refdefs
  = note: `#[warn(clippy::doc_nested_refdefs)]` on by default
help: for an intra-doc link, add `[]` between the label and the colon
  |
3 | //! - [link][]: 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 is probably intended as an intra-doc link. If it is really supposed to be a reference definition, it can be written outside of the list item or quote.

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

//! - [link]: description

Write this instead

//! - [link][]: description (for intra-doc link)
//!
//! [link]: destination (for link reference definition)

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_nested_refdefs)]
fn my_function() { /* ... */ }

Whole crate (Cargo.toml)

[lints.clippy]
doc_nested_refdefs = "allow"

One run

cargo clippy -- -A clippy::doc-nested-refdefs

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.85.0added in Rust

Clippy's own documentation

What it does

Warns if a link reference definition appears at the start of a list item or quote.

Why is this bad?

This is probably intended as an intra-doc link. If it is really supposed to be a reference definition, it can be written outside of the list item or quote.

Example

//! - [link]: description

Use instead:

//! - [link][]: description (for intra-doc link)
//!
//! [link]: destination (for link reference definition)

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?