linux-kernel - Re: [PATCH 0/4] Some kernel-doc fixes

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: <20250520163102.611cecc6@sal.lan>
Date: Tue, 20 May 2025 16:31:02 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Cc: Jonathan Corbet <corbet@....net>, Stephen Rothwell
 <sfr@...b.auug.org.au>, Nicolas Schier <nicolas.schier@...ux.dev>, Akira
 Yokosawa <akiyks@...il.com>, Randy Dunlap <rdunlap@...radead.org>,
 linux-doc@...r.kernel.org, linux-kbuild@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH 0/4] Some kernel-doc fixes

Em Tue, 20 May 2025 17:17:56 +0300
Andy Shevchenko <andriy.shevchenko@...ux.intel.com> escreveu:

> On Tue, May 20, 2025 at 03:33:05PM +0200, Mauro Carvalho Chehab wrote:
> > Hi Jon,
> > 
> > Let me consolidate some patches on a single PR to make life simpler
> > for you. Those should address Stephen and Akira's concerns with
> > regards to KernelDoc class usage via sphinx kerneldoc.py extension.
> > 
> > Patch 1:	don't let Sphinx suppress errors/warnings;
> > Patch 2:	fix a KeyError when trying to acess data from non-existing files;
> > Patch 3:	add try/except blocks to avoid crashes when handling bad
> > 	kernel-doc markups;
> > Patch 4:	makes Lore and kernel-doc ML receive patches related
> > 	to kernel-doc.py and get_abi.py.
> > 
> > Patches 1 to 3 were already submitted on separate series. Patch 4 is new.  
> 
> Can we actually utilise CONFIG_WERROR to fail the build. If yes, the build will
> be failed. This is in align with the warnings in the C code.

It makes sense to me - either to use CONFIG_WERROR or to have something like:

	make SPHINX_WERROR=1 htmldocs

Btw, kernel-doc.pl (*) and kernel-doc.py have several command-line parameters
to control warnings:

  $ ./scripts/kernel-doc --help
  ... 
  -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
  -Wshort-desc, -Wshort-description, --wshort-desc
                        Warns if initial short description is missing
  -Wcontents-before-sections, --wcontents-before-sections
                        
                        Warns if there are contents before sections (deprecated).
                        
                        This option is kept just for backward-compatibility, but it does nothing,
                        neither here nor at the original Perl script.
  -Wall, --wall         Enable all types of warnings
  -Werror, --werror     Treat warnings as errors.
  ...

(*) from the above, only -Werror is documented at the Perl version.

In the future, I'm planning to do some work to improve it - including
removing the deprecated -Wcontents-before-sections.

But anyway this is out of the scope of this series, as we're aiming
to be bug-compatible with kernel-doc.pl. The crashes were unintended.

Regards,
Mauro