Clippy lint · Nursery · checked with Clippy 0.1.99

clippy::too_long_first_doc_paragraph: Checks if the first paragraph in the documentation of items listed in the module page is too long

What it meansChecks if the first paragraph in the documentation of items listed in the module page is too long. It is in the nursery group and off by default.

Does it matter?

Documentation will show the first paragraph of the docstring in the summary page of a module. Having a nice, short summary in the first paragraph is part of writing good docs.

New lints still being finished. Off by default and may have false positives.

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

/// A very short summary.
/// A much longer explanation that goes into a lot more detail about
/// how the thing works, possibly with doclinks and so one,
/// and probably spanning a many rows.
struct Foo {}

Write this instead

/// A very short summary.
///
/// A much longer explanation that goes into a lot more detail about
/// how the thing works, possibly with doclinks and so one,
/// and probably spanning a many rows.
struct Foo {}

Turn it off, or on

It is off by default. To use it, set it to warn or deny:

Whole crate (Cargo.toml)

[lints.clippy]
too_long_first_doc_paragraph = "warn"

In code

#![warn(clippy::too_long_first_doc_paragraph)]

One run

cargo clippy -- -W clippy::too-long-first-doc-paragraph

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.

Nurserygroup

allowdefault level

yesfixed by cargo clippy --fix

1.82.0added in Rust

Clippy's own documentation

What it does

Checks if the first paragraph in the documentation of items listed in the module page is too long.

Why is this bad?

Documentation will show the first paragraph of the docstring in the summary page of a module. Having a nice, short summary in the first paragraph is part of writing good docs.

Example

/// A very short summary.
/// A much longer explanation that goes into a lot more detail about
/// how the thing works, possibly with doclinks and so one,
/// and probably spanning a many rows.
struct Foo {}

Use instead:

/// A very short summary.
///
/// A much longer explanation that goes into a lot more detail about
/// how the thing works, possibly with doclinks and so one,
/// and probably spanning a many rows.
struct Foo {}

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?