docs: kdoc: remove an extraneous strip() call

...the variable in question was already strip()ed at the top of the loop.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by:

docs: kdoc: remove an extraneous strip() call

...the variable in question was already strip()ed at the top of the loop.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-9-corbet@lwn.net

show more ...

docs: kdoc: rework the rewrite_struct_members() main loop

Adopt a more Pythonic form for the main loop of this function, getting rid
of the "while True:" construction and making the actual loop inva

docs: kdoc: rework the rewrite_struct_members() main loop

Adopt a more Pythonic form for the main loop of this function, getting rid
of the "while True:" construction and making the actual loop invariant
explicit.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-8-corbet@lwn.net

show more ...

docs: kdoc: split struct-member rewriting out of dump_struct()

The massive loop that massages struct members shares no data with the rest
of dump_struct(); split it out into its own function. Code

docs: kdoc: split struct-member rewriting out of dump_struct()

The massive loop that massages struct members shares no data with the rest
of dump_struct(); split it out into its own function. Code movement only,
no other changes.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-7-corbet@lwn.net

show more ...

docs: kdoc: split top-level prototype parsing out of dump_struct()

Move the initial split of the prototype into its own function in the
ongoing effort to cut dump_struct() down to size.

Reviewed-by

docs: kdoc: split top-level prototype parsing out of dump_struct()

Move the initial split of the prototype into its own function in the
ongoing effort to cut dump_struct() down to size.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-6-corbet@lwn.net

show more ...

docs: kdoc: move the prefix transforms out of dump_struct()

dump_struct is one of the longest functions in the kdoc_parser class,
making it hard to read and reason about. Move the definition of the

docs: kdoc: move the prefix transforms out of dump_struct()

dump_struct is one of the longest functions in the kdoc_parser class,
making it hard to read and reason about. Move the definition of the prefix
transformations out of the function, join them with the definition of
"attribute" (which was defined at the top of the file but only used here),
and reformat the code slightly for shorter line widths.

Just code movement in the end.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-5-corbet@lwn.net

show more ...

docs: kdoc: backslashectomy in kdoc_parser

A lot of the regular expressions in this file have extraneous backslashes
that may have been needed in Perl, but aren't helpful here. Take them out
to red

docs: kdoc: backslashectomy in kdoc_parser

A lot of the regular expressions in this file have extraneous backslashes
that may have been needed in Perl, but aren't helpful here. Take them out
to reduce slightly the visual noise.

Escaping of (){}[] has been left in place, even when unnecessary, for
visual clarity.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-4-corbet@lwn.net

show more ...

docs: kdoc: Move a regex line in dump_struct()

The complex struct_members regex was defined far from its use; bring the
two together. Remove some extraneous backslashes while making the move.

Revi

docs: kdoc: Move a regex line in dump_struct()

The complex struct_members regex was defined far from its use; bring the
two together. Remove some extraneous backslashes while making the move.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-3-corbet@lwn.net

show more ...

docs: kdoc: consolidate the stripping of private struct/union members

There were two locations duplicating the logic of stripping private members
and associated comments; coalesce them into one, and

docs: kdoc: consolidate the stripping of private struct/union members

There were two locations duplicating the logic of stripping private members
and associated comments; coalesce them into one, and add some comments
describing what's going on.

Output change: we now no longer add extraneous white space around macro
definitions.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807211639.47286-2-corbet@lwn.net

show more ...

Merge tag 'docs-6.17' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
"It has been a relatively busy cycle for docs, especially the build
system:

- The Perl kernel

Merge tag 'docs-6.17' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
"It has been a relatively busy cycle for docs, especially the build
system:

- The Perl kernel-doc script was added to 2.3.52pre1 just after the
turn of the millennium. Over the following 25 years, it accumulated
a vast amount of cruft, all in a language few people want to deal
with anymore. Mauro's Python replacement in 6.16 faithfully
reproduced all of the cruft in the hope of avoiding regressions.

Now that we have a more reasonable code base, though, we can work
on cleaning it up; many of the changes this time around are toward
that end.

- A reorganization of the ext4 docs into the usual TOC format.

- Various Chinese translations and updates.

- A new script from Mauro to help with docs-build testing.

- A new document for linked lists

- A sweep through MAINTAINERS fixing broken GitHub git:// repository
links.

...and lots of fixes and updates"

* tag 'docs-6.17' of git://git.lwn.net/linux: (147 commits)
scripts: add origin commit identification based on specific patterns
sphinx: kernel_abi: fix performance regression with O=<dir>
Documentation: core-api: entry: Replace deprecated KVM entry/exit functions
docs: fault-injection: drop reference to md-faulty
docs: document linked lists
scripts: kdoc: make it backward-compatible with Python 3.7
docs: kernel-doc: emit warnings for ancient versions of Python
Documentation/rtla: Describe exit status
Documentation/rtla: Add include common_appendix.rst
docs: kernel: Clarify printk_ratelimit_burst reset behavior
Documentation: ioctl-number: Don't repeat macro names
Documentation: ioctl-number: Shorten macros table
Documentation: ioctl-number: Correct full path to papr-physical-attestation.h
Documentation: ioctl-number: Extend "Include File" column width
Documentation: ioctl-number: Fix linuxppc-dev mailto link
overlayfs.rst: fix typos
docs: kdoc: emit a warning for ancient versions of Python
docs: kdoc: clean up check_sections()
docs: kdoc: directly access the always-there KdocItem fields
docs: kdoc: straighten up dump_declaration()
...

show more ...