linux-kernel - Re: [RFC] Proposal to relax warnings of htmldocs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <f7d0e554-b6ac-49ee-4caf-640967bc1053@amd.com>
Date:   Wed, 16 Aug 2023 10:12:56 -0500
From:   Carlos Bilbao <carlos.bilbao@....com>
To:     Jani Nikula <jani.nikula@...ux.intel.com>,
        Matthew Wilcox <willy@...radead.org>,
        Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
Cc:     Jonathan Corbet <corbet@....net>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        Avadhut Naik <Avadhut.Naik@....com>,
        Miguel Ojeda <ojeda@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>
Subject: Re: [RFC] Proposal to relax warnings of htmldocs

On 8/16/23 06:01, Jani Nikula wrote:
> On Tue, 15 Aug 2023, Matthew Wilcox <willy@...radead.org> wrote:
>> On Tue, Aug 15, 2023 at 08:35:40PM +0200, Miguel Ojeda wrote:
>>> On Tue, Aug 15, 2023 at 8:23 PM Jonathan Corbet <corbet@....net> wrote:
>>>>
>>>> As an alternative, of course, we could consider turning off those
>>>> specific warnings entirely for normal builds.
>>>
>>> It could be nice to get to enforce warning-free builds as soon as possible.
>>>
>>> Perhaps we could move those to a `W=1`-like group and clean them over
>>> time instead? Or do we have that already?
>>
>> I think the problem is that we don't run kernel-doc by default.  Instead,
>> it's only run for W=1 (and higher) builds.  That's why Carlos doesn't
>> see the problems he is introducing in his own builds.  Of course, if
>> AMD required building with W=1 then they'd see these problems earlier
>> in their own testing.  Apparently they don't.
>>
>> Is it time to just run kernel-doc by default?  There aren't _that_
>> many kernel-doc warnings now.  Not compared to how they used to be.
>> And enabling them for everyone means that new ones won't sneak in.
>> I haven't timed how much extra time kernel-doc adds to a build.
>> Perhaps that's infeasible.
> 
> Personally, I believe it's easier to get at a warning free build (both
> compiler W=1 warnings as well as kernel-doc) by doing it driver and
> subsystem at a time, instead of, say, one warning at a time across the
> entire kernel. It's just too much of a burden to fix the entire kernel
> to enable a warning across the board.
> 
> To that end, the i915 Makefile enables a lot more warnings than the
> defaults, and the developers and CI run the compiler and kernel-doc with
> -Werror. No new warnings get introduced.
> 
> What I'd hope for is build system support to enable W=1
> compiler/kernel-doc warnings for a subdir with a few lines at most,
> instead of duplicating and copy-pasting tens of lines from
> scripts/Makefile.extrawarn like we have to do now.

That sounds feasible but, well, I actually proposed the opposite approach.
I wanted to "relax" the warnings (see RFC Subject) rather than making them
more strict by default.

My concern is that W=1 (by default) may theoretically result in a clean
`make htmldocs` but it won't in practice. Not all developers prioritize
good documentation like the folks from i915, and that may lead to
unaddressed warnings or worst, less interest in documenting the code. Isn't
it the case that some of these higher-control warnings don't really have
much effect in real life? And shoukd W=1 become the default, are we going
to be able to enforce that level of control?

If W=1 is decided to be the best approach I'm happy to help with that.

> 
> 
> BR,
> Jani.
> 
> 

Thanks,
Carlos