rust-lang
Add new style lint: Warn if first paragraph in docstring is too long.
What it does
Warn when the first paragraph of a docstring is overly long.
cargo doc will show the first paragraph of the doscstring in the summary page on a crate and module, so having a nice, short summary in the first paragraph is part of writing good docs.
A very long first paragraph can be easily created by mistake. That's because cargo doc (and most markdown viewers) ignores single newlines and requires a double newline to register as a new paragraph. So this is one paragraph:
/// 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 { … }
while this is two paragraphs:
/// 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 { … }
Advantage
An overly long first paragraph makes for a bad summary, and a bad overview in a docs page for a crate:
Here's how it looks with an added ///:
Drawbacks
It might be annoying if the length limit is set too low.
I suggest a default of 80 chars, but configurable in clippy.toml.
Example
/// A rectangular region of space.
/// Usually a [`Rect`] has a positive (or zero) size,
/// and then [`Self::min`] `<=` [`Self::max`].
/// In these cases [`Self::min`] is the left-top corner
/// and [`Self::max`] is the right-bottom corner.
/// A rectangle is allowed to have a negative size, which happens when the order
/// of `min` and `max` are swapped. These are usually a sign of an error.
/// Normally the unit is points (logical pixels) in screen space coordinates.
/// `Rect` does NOT implement `Default`, because there is no obvious default value.
/// [`Rect::ZERO`] may seem reasonable, but when used as a bounding box, [`Rect::NOTHING`]
/// is a better default - so be explicit instead!
#[derive(Clone, Copy, Eq, PartialEq)]
struct Rect { … }
Could be written as:
/// A rectangular region of space.
///
/// Usually a [`Rect`] has a positive (or zero) size,
/// and then [`Self::min`] `<=` [`Self::max`].
/// In these cases [`Self::min`] is the left-top corner
/// and [`Self::max`] is the right-bottom corner.
/// A rectangle is allowed to have a negative size, which happens when the order
/// of `min` and `max` are swapped. These are usually a sign of an error.
/// Normally the unit is points (logical pixels) in screen space coordinates.
/// `Rect` does NOT implement `Default`, because there is no obvious default value.
/// [`Rect::ZERO`] may seem reasonable, but when used as a bounding box, [`Rect::NOTHING`]
/// is a better default - so be explicit instead!
#[derive(Clone, Copy, Eq, PartialEq)]
pub struct Rect {
Note that we should suggest the added extra newline, as no doubt a lot of programmers aren't aware of this.
