Re: [PATCH] rust: fix clippy::too-long-first-doc-paragraph

[Benno Lossin <benno.lossin@proton.me>]

On 16.02.25 01:12, Charalampos Mitrodimas wrote:
> Benno Lossin <benno.lossin@proton.me> writes:
> 
>> When running `make LLVM=1 CLIPPY=1` on my machine, I get this error:
>>
>>     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)]`
>>
>> Thus add a short one-line description.
>>
>> Fixes: ea7e18289f44 ("rust: implement generic driver registration")
>> Signed-off-by: Benno Lossin <benno.lossin@proton.me>
>> ---
>> The error also occurs in v6.14-rc1, so it must have slipped through our
>> testing, which I find a bit strange. Also nobody reported it for rc1, so
>> maybe this is only something that I encountered?
>> ---
>>  rust/kernel/driver.rs | 2 ++
>>  1 file changed, 2 insertions(+)
>>
>> diff --git a/rust/kernel/driver.rs b/rust/kernel/driver.rs
>> index 2a16d5e64e6c..65c9c1776556 100644
>> --- a/rust/kernel/driver.rs
>> +++ b/rust/kernel/driver.rs
>> @@ -10,6 +10,8 @@
>>  use core::pin::Pin;
>>  use macros::{pin_data, pinned_drop};
>>
>> +/// Generic interface for subsystem driver registrations.
>> +///
>>  /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform,
>>  /// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
>>  /// unregister a driver of the particular type (`RegType`).
>>
>> base-commit: a64dcfb451e254085a7daee5fe51bf22959d52d3
> 
> Hi,
> 
> I cannot reproduce this as-is, but adding
> "-Wclippy::too_long_first_doc_paragraph" to the "rust_common_flags" in
> the Makefile reproduces it. Maybe try adding it there in your patch?

I have done some more digging and bisected my Rust version. It turns out
I was on a rather old nightly from last September. I also don't get the
error on a newer compiler version. My bisection identified that the
error last occurs in nightly 2024-10-18, so from 2024-10-19 onwards it
compiles without the error.
So probably `-Wclippy::all` implied the `too_long_first_doc_paragraph`
lint in that version. That is probably because of [1]. It changes the
lint from style to nursery.

[1]: https://github.com/rust-lang/rust-clippy/pull/13551

So we don't need this patch, as it seems this never hit stable. However,
there is already a patch fixing what this lint reports: 2f390cc58943
("rust: provide proper code documentation titles").

I think it's a good lint, so maybe we should turn it on?

---
Cheers,
Benno

> 
> diff --git a/Makefile b/Makefile
> index 89628e354..e1b14fb68 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
>