Clippy lints / Style
Clippy lint · Style · checked with Clippy 0.1.99
clippy::doc_lazy_continuation: doc quote line without `>` marker
What it meansIn CommonMark Markdown, the language used to write doc comments, a paragraph nested within a list or block quote does not need any line after the first one to be indented or marked. The specification calls this a “lazy paragraph continuation.” It is in the style group and warns by default.
What you see
warning: doc quote line without `>` marker --> main.rs:6:5 | 6 | /// < 1 | partially see-through | ^ | = help: if this not intended to be a quote at all, escape it with `\>` = help: for further information visit https://rust-lang.github.io/rust-clippy/stable/index.html#doc_lazy_continuation = note: `#[warn(clippy::doc_lazy_continuation)]` on by default help: add markers to start of line | 6 | /// > < 1 | partially see-through | +
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 easy to write but hard to read. Lazy continuations makes unintended markers hard to see, and make it harder to deduce the document’s intended structure.
Code that works but is not idiomatic Rust. Warns by default.
How to fix it
Clippy can fix this one for you: run cargo clippy --fix (add --allow-dirty if you have uncommitted changes). Review the diff before you commit.
Flagged
/// Range | Description
/// ----- | -----------
/// >= 1 | fully opaque
/// < 1 | partially see-through
fn set_opacity(opacity: f32) {}
Write this instead
/// Range | Description
/// ----- | -----------
/// \>= 1 | fully opaque
/// < 1 | partially see-through
fn set_opacity(opacity: f32) {}
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_lazy_continuation)]
fn my_function() { /* ... */ }Whole crate (Cargo.toml)
[lints.clippy]
doc_lazy_continuation = "allow"One run
cargo clippy -- -A clippy::doc-lazy-continuationThe [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.
Clippy's own documentation
What it does
In CommonMark Markdown, the language used to write doc comments, a paragraph nested within a list or block quote does not need any line after the first one to be indented or marked. The specification calls this a “lazy paragraph continuation.”
Why is this bad?
This is easy to write but hard to read. Lazy continuations makes unintended markers hard to see, and make it harder to deduce the document’s intended structure.
Example
This table is probably intended to have two rows, but it does not. It has zero rows, and is followed by a block quote.
/// Range | Description
/// ----- | -----------
/// >= 1 | fully opaque
/// < 1 | partially see-through
fn set_opacity(opacity: f32) {}
Fix it by escaping the marker:
/// Range | Description
/// ----- | -----------
/// \>= 1 | fully opaque
/// < 1 | partially see-through
fn set_opacity(opacity: f32) {}
This example is actually intended to be a list:
/// * Do nothing.
/// * Then do something. Whatever it is needs done,
/// it should be done right now.
Fix it by indenting the list contents:
/// * Do nothing.
/// * Then do something. Whatever it is needs done,
/// it should be done right now.
From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.
Related lints
- needless_returnunneeded `return` statement
- new_without_defaultChecks for public types with a pub fn new() -> Self method and no implementation of Default
- len_zeroChecks for getting the length of something via .len() just to compare to zero, and suggests using .is_empty() where applicable
- disallowed_methodsDenies the configured methods and functions in clippy.toml Note: Even though this lint is warn-by-default, it will only trigger if methods are defined in the clippy.toml file
- disallowed_namesuse of a disallowed/placeholder name `foo`
- disallowed_typesDenies the configured types in clippy.toml. Note: Even though this lint is warn-by-default, it will only trigger if types are defined in the clippy.toml file
- doc_overindented_list_itemsDetects overindented list items in doc comments where the continuation lines are indented more than necessary
- double_must_usethis function has a `#[must_use]` attribute with no message, but returns a type already considered as `#[must_use]`
- duplicate_underscore_argument`a` already exists, having another argument having almost the same name makes code comprehension and documentation more difficult
All 847 Clippy lints · Rust compiler errors · Cargo.toml checker
Up next
Related lintclippy::needless_returnunneeded `return` statementRead it next →Did this answer your question?