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

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

On 16.02.25 13:40, Miguel Ojeda wrote:
> On Sun, Feb 16, 2025 at 1:18 PM Benno Lossin <benno.lossin@proton.me> wrote:
>>
>> 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.
> 
> Thanks Benno, that is very useful and saved me some work.

My pleasure :)

>> 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
> 
> Yeah, sometimes that happens when working regularly with nightly over time.
> 
> There is an upside, trying to look at it positively, which is that it
> gives us something to look into from time to time (i.e. the new lint)
> and give feedback, and sometimes we can clean it up anyway, even if
> the lint is broken and we cannot enable it just yet :)

Yeah that is true.

>> 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?
> 
> Agreed, we should -- it is something we tell people from time to time
> to fix in review, so hopefully it will make patches better before the
> review phase.
> 
> ...well, assuming it works well enough, given it was moved to nursery,
> e.g. in the linked Zulip thread in your link above they point to
> https://github.com/rust-lang/rust-clippy/issues/13315 and

I don't think that this one is bad. Of course it would be nice if only
the rendered form would be considered, but there might also be people
reading it directly in the code, so it could actually be a good idea to
also keep the raw text short.
In the case of long links, one can easily work around it by just not
using an inline link. (so having [text with link] and then after the
paragraph `[text with link]: link`.)

> https://github.com/rust-lang/rust-clippy/issues/13538, which we may or
> may not care about.

This one just seems like a nice-to-have, but not a deal breaker.

IMO we can enable the lint (since the instance fixed in this patch is
the only error I get with that lint) and just see how it behaves.

---
Cheers,
Benno