[PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

[PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

[Benno Lossin]

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
 
-- 
2.47.2

Re: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

[Charalampos Mitrodimas]

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>

Re: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

[Miguel Ojeda]

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

Re: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

[Benno Lossin]

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