| Message ID | 20250216213827.3752586-2-benno.lossin@proton.me (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | None | expand |
Benno Lossin <benno.lossin@proton.me> writes: > Introduced in Rust 1.82.0 [1], this lint ensures that the first line of > documentation is short. That is because those lines get rendered in the > html version of the docs directly next to the items and should therefore > be short. > Additionally, a short first sentence might help developers remember the > rest of the documentation if they have read it already before. > > Reviewers have pointed this out manually on several occasions, thus > enable the lint. > > Here is an example error fixed in the previous commit: > > error: first doc comment paragraph is too long > --> rust/kernel/driver.rs:13:1 > | > 13 | / /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform, > 14 | | /// Amba, etc.) to provide the corresponding subsystem specific implementation to register / > 15 | | /// unregister a driver of the particular type (`RegType`). > 16 | | /// > 17 | | /// For instance, the PCI subsystem would set `RegType` to `bindings::pci_driver` and call > | |_^ > | > = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph > = note: `-D clippy::too-long-first-doc-paragraph` implied by `-D warnings` > = help: to override `-D warnings` add `#[allow(clippy::too_long_first_doc_paragraph)]` > > error: aborting due to 1 previous error > > The exact length can be configured in the .clippy.toml if we need to do > so. > > Link: https://github.com/rust-lang/rust-clippy/issues/12989 [1] > Signed-off-by: Benno Lossin <benno.lossin@proton.me> > --- > Makefile | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/Makefile b/Makefile > index 9e0d63d9d94b..d00cbeb63714 100644 > --- a/Makefile > +++ b/Makefile > @@ -486,6 +486,7 @@ export rust_common_flags := --edition=2021 \ > -Wclippy::undocumented_unsafe_blocks \ > -Wclippy::unnecessary_safety_comment \ > -Wclippy::unnecessary_safety_doc \ > + -Wclippy::too-long-first-doc-paragraph \ > -Wrustdoc::missing_crate_level_docs \ > -Wrustdoc::unescaped_backticks Reviewed-by: Charalampos Mitrodimas <charmitro@posteo.net>
On Sun, Feb 16, 2025 at 10:38 PM Benno Lossin <benno.lossin@proton.me> wrote: > > Introduced in Rust 1.82.0 [1], this lint ensures that the first line of We will need to ignore unknown lints so that it does not warn on older compilers. We should probably do it conditionally instead -- it requires some rework to do it for everything, but we can easily do it for kernel code. I can tweak it and put this patch into my warning rework series -- I had to send the v2 of that anyway. Sounds good? Thanks! Cheers, Miguel
On 17.02.25 19:07, Miguel Ojeda wrote: > On Sun, Feb 16, 2025 at 10:38 PM Benno Lossin <benno.lossin@proton.me> wrote: >> >> Introduced in Rust 1.82.0 [1], this lint ensures that the first line of > > We will need to ignore unknown lints so that it does not warn on older > compilers. > > We should probably do it conditionally instead -- it requires some > rework to do it for everything, but we can easily do it for kernel code. Ah yeah forgot about that. That's a good point. > I can tweak it and put this patch into my warning rework series -- I > had to send the v2 of that anyway. Sounds good? Sure! --- Cheers, Benno
diff --git a/Makefile b/Makefile index 9e0d63d9d94b..d00cbeb63714 100644 --- a/Makefile +++ b/Makefile @@ -486,6 +486,7 @@ export rust_common_flags := --edition=2021 \ -Wclippy::undocumented_unsafe_blocks \ -Wclippy::unnecessary_safety_comment \ -Wclippy::unnecessary_safety_doc \ + -Wclippy::too-long-first-doc-paragraph \ -Wrustdoc::missing_crate_level_docs \ -Wrustdoc::unescaped_backticks
Introduced in Rust 1.82.0 [1], this lint ensures that the first line of documentation is short. That is because those lines get rendered in the html version of the docs directly next to the items and should therefore be short. Additionally, a short first sentence might help developers remember the rest of the documentation if they have read it already before. Reviewers have pointed this out manually on several occasions, thus enable the lint. Here is an example error fixed in the previous commit: error: first doc comment paragraph is too long --> rust/kernel/driver.rs:13:1 | 13 | / /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform, 14 | | /// Amba, etc.) to provide the corresponding subsystem specific implementation to register / 15 | | /// unregister a driver of the particular type (`RegType`). 16 | | /// 17 | | /// For instance, the PCI subsystem would set `RegType` to `bindings::pci_driver` and call | |_^ | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph = note: `-D clippy::too-long-first-doc-paragraph` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::too_long_first_doc_paragraph)]` error: aborting due to 1 previous error The exact length can be configured in the .clippy.toml if we need to do so. Link: https://github.com/rust-lang/rust-clippy/issues/12989 [1] Signed-off-by: Benno Lossin <benno.lossin@proton.me> --- Makefile | 1 + 1 file changed, 1 insertion(+)