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