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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 20 May 2025 17:17:56 +0300
Andy Shevchenko <andriy.shevchenko@linux.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