[REGRESSION BISECTED] Unexpected section title false positive warnings on DOC: directive

[REGRESSION BISECTED] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[this is actually a repost of [1] since that thread didn't get any attention
from the regressor.]

Hi,

Building htmldocs on docs-next currenly produces about 80 new warnings; which
all of them are unexpected section title on DOC: kernel-doc directive, like:

/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.

Userspace I/O
------------- [docutils]
WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
/home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.

Ring Design
----------- [docutils]
WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Ring Design' ./include/uapi/linux/target_core_user.h' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: (SEVERE/4) Unexpected section title.\n\nRing Design\n-----------')

These turns out to be false-positive as touching the source file in question
(e.g. drivers/target/target_core_user.c) and making htmldocs again makes the
regression go away for the corresponding docs.

Bisection (with git-bisect(1)) points to bea467aa5da1f5 ("docs: media:
v4l2-ioctl.h: document two global variables") as the first bad commit, even
though that I suspect that bdd1cf87847ff6 ("kernel-doc: add support to handle
DEFINE_ variables") may be the actual culprit (regressor).

The full bisection log:

git bisect start
# status: waiting for both good and bad commits
# bad: [7f3c3a0a9103dc92c823f27db3284ac2914e7558] MAINTAINERS: Add doc files on real-time support to Real-time Linux
git bisect bad 7f3c3a0a9103dc92c823f27db3284ac2914e7558
# status: waiting for good commit(s), bad commit known
# good: [9448598b22c50c8a5bb77a9103e2d49f134c9578] Linux 6.19-rc2
git bisect good 9448598b22c50c8a5bb77a9103e2d49f134c9578
# bad: [5188f6bd408f937d81c0c37eb59ddc1035cd912c] docs: admin: devices: /dev/sr<N> for SCSI CD-ROM
git bisect bad 5188f6bd408f937d81c0c37eb59ddc1035cd912c
# bad: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables
git bisect bad bea467aa5da1f51834501da3ac3c40204027a221
# good: [82e87387f6e2af9f69a7528733e953fd22e815aa] Documentation: kernel-hacking: Remove comma
git bisect good 82e87387f6e2af9f69a7528733e953fd22e815aa
# good: [bdd1cf87847ff6aaadd53a185209d2bb2db72165] kernel-doc: add support to handle DEFINE_ variables
git bisect good bdd1cf87847ff6aaadd53a185209d2bb2db72165
# first bad commit: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables

Mauro: Since you're the author of regressor, can you please take a look on it?

Thanks.

#regzbot introduced: bea467aa5da1f5

[1]: https://lore.kernel.org/regressions/aUuLHzk5jdyBAxD7@archie.me/

-- 
An old man doll... just what I always wanted! - Clara

Re: [REGRESSION BISECTED] Unexpected section title false positive warnings on DOC: directive

[Thorsten Leemhuis]

On 2/23/26 03:38, Bagas Sanjaya wrote:
> [this is actually a repost of [1] since that thread didn't get any attention
> from the regressor.]

"Regressor" feels like a odd word choice here (one that according to
lore nobody has used before). Makes way more sense (and at least to me
feels more polite) to say something like "the culprit's author (Mauro)"
– especially as the person might have forgotten already that they
authored the change in questions.

> Building htmldocs on docs-next currenly produces about 80 new warnings; which
> all of them are unexpected section title on DOC: kernel-doc directive, like:

For now it looks like your the only one to see that problem, so maybe
it's something that is odd on your systems; and given that these are
warnings I'm included to stop tracking this as a regression.

Ciao, Thorsten

> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
> 
> Userspace I/O
> ------------- [docutils]
> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
> 
> Ring Design
> ----------- [docutils]
> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Ring Design' ./include/uapi/linux/target_core_user.h' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: (SEVERE/4) Unexpected section title.\n\nRing Design\n-----------')
> 
> These turns out to be false-positive as touching the source file in question
> (e.g. drivers/target/target_core_user.c) and making htmldocs again makes the
> regression go away for the corresponding docs.
> 
> Bisection (with git-bisect(1)) points to bea467aa5da1f5 ("docs: media:
> v4l2-ioctl.h: document two global variables") as the first bad commit, even
> though that I suspect that bdd1cf87847ff6 ("kernel-doc: add support to handle
> DEFINE_ variables") may be the actual culprit (regressor).
> 
> The full bisection log:
> 
> git bisect start
> # status: waiting for both good and bad commits
> # bad: [7f3c3a0a9103dc92c823f27db3284ac2914e7558] MAINTAINERS: Add doc files on real-time support to Real-time Linux
> git bisect bad 7f3c3a0a9103dc92c823f27db3284ac2914e7558
> # status: waiting for good commit(s), bad commit known
> # good: [9448598b22c50c8a5bb77a9103e2d49f134c9578] Linux 6.19-rc2
> git bisect good 9448598b22c50c8a5bb77a9103e2d49f134c9578
> # bad: [5188f6bd408f937d81c0c37eb59ddc1035cd912c] docs: admin: devices: /dev/sr<N> for SCSI CD-ROM
> git bisect bad 5188f6bd408f937d81c0c37eb59ddc1035cd912c
> # bad: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables
> git bisect bad bea467aa5da1f51834501da3ac3c40204027a221
> # good: [82e87387f6e2af9f69a7528733e953fd22e815aa] Documentation: kernel-hacking: Remove comma
> git bisect good 82e87387f6e2af9f69a7528733e953fd22e815aa
> # good: [bdd1cf87847ff6aaadd53a185209d2bb2db72165] kernel-doc: add support to handle DEFINE_ variables
> git bisect good bdd1cf87847ff6aaadd53a185209d2bb2db72165
> # first bad commit: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables
> 
> Mauro: Since you're the author of regressor, can you please take a look on it?
> 
> Thanks.
> 
> #regzbot introduced: bea467aa5da1f5
> 
> [1]: https://lore.kernel.org/regressions/aUuLHzk5jdyBAxD7@archie.me/
> 

Re: [REGRESSION BISECTED] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1051 bytes --]

On Wed, Mar 04, 2026 at 04:31:33PM +0100, Thorsten Leemhuis wrote:
> On 2/23/26 03:38, Bagas Sanjaya wrote:
> > [this is actually a repost of [1] since that thread didn't get any attention
> > from the regressor.]
> 
> "Regressor" feels like a odd word choice here (one that according to
> lore nobody has used before). Makes way more sense (and at least to me
> feels more polite) to say something like "the culprit's author (Mauro)"
> – especially as the person might have forgotten already that they
> authored the change in questions.

I was using bugzilla lingo, though.

> 
> > Building htmldocs on docs-next currenly produces about 80 new warnings; which
> > all of them are unexpected section title on DOC: kernel-doc directive, like:
> 
> For now it looks like your the only one to see that problem, so maybe
> it's something that is odd on your systems; and given that these are
> warnings I'm included to stop tracking this as a regression.

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]