docs: kdoc: Move content handling into KernelEntry

Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
s

docs: kdoc: Move content handling into KernelEntry

Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

docs: kdoc: remove KernelEntry::in_doc_sect

This field is not used for anything, just get rid of it.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: kdoc: finish disentangling the BODY and SPECIAL_SECTION states

Move the last SPECIAL_SECTION special case into the proper handler
function, getting rid of more if/then/else logic. The leading

docs: kdoc: finish disentangling the BODY and SPECIAL_SECTION states

Move the last SPECIAL_SECTION special case into the proper handler
function, getting rid of more if/then/else logic. The leading-space
tracking was tightened up a bit in the move. Add some comments describing
what is going on.

No changes to the generated output.

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

show more ...

docs: kdoc: Add some comments to process_decl()

Now that the function can actually fit into a human brain, add a few
comments. While I was at it, I switched to the trim_whitespace() helper
rather t

docs: kdoc: Add some comments to process_decl()

Now that the function can actually fit into a human brain, add a few
comments. While I was at it, I switched to the trim_whitespace() helper
rather than open-coding it.

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

show more ...

docs: kdoc: coalesce the end-of-comment processing

Separate out the end-of-comment logic into its own helper and remove the
duplicated code introduced earlier.

Reviewed-by: Mauro Carvalho Chehab <m

docs: kdoc: coalesce the end-of-comment processing

Separate out the end-of-comment logic into its own helper and remove the
duplicated code introduced earlier.

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

show more ...

docs: kdoc: rework the handling of SPECIAL_SECTION

Move the recognition of this state to when we enter it, rather than when we
exit, eliminating some twisty logic along the way.

Some changes in out

docs: kdoc: rework the handling of SPECIAL_SECTION

Move the recognition of this state to when we enter it, rather than when we
exit, eliminating some twisty logic along the way.

Some changes in output do result from this shift, generally for kerneldoc
comments that do not quite fit the format. See, for example,
struct irqdomain. As far as I can tell, the new behavior is more correct
in each case.

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

show more ...

docs: kdoc: coalesce the new-section handling

Merge the duplicated code back into a single implementation. Code movement
only, no logic changes.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@

docs: kdoc: coalesce the new-section handling

Merge the duplicated code back into a single implementation. Code movement
only, no logic changes.

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

show more ...

docs: kdoc: split out the special-section state

The state known as BODY_WITH_BLANK_LINE really, in a convoluted way,
indicates a "special section" that is terminated by a blank line or the
beginning

docs: kdoc: split out the special-section state

The state known as BODY_WITH_BLANK_LINE really, in a convoluted way,
indicates a "special section" that is terminated by a blank line or the
beginning of a new section. That is either "@param: desc" sections, or the
weird "context" section that plays by the same rules.

Rename the state to SPECIAL_SECTION and split its processing into a
separate function; no real changes to the logic yet.

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

show more ...

docs: kdoc: separate out the handling of the declaration phase

The BODY_MAYBE state really describes the "we are in a declaration" state.
Rename it accordingly, and split the handling of this state

docs: kdoc: separate out the handling of the declaration phase

The BODY_MAYBE state really describes the "we are in a declaration" state.
Rename it accordingly, and split the handling of this state out from that
of the other BODY* states. This change introduces a fair amount of
duplicated code that will be coalesced in a later patch.

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

show more ...

docs: kdoc: consolidate the "begin section" logic

Pull the repeated "begin a section" logic into a single place and hide it
within the KernelEntry class.

Reviewed-by: Mauro Carvalho Chehab <mchehab

docs: kdoc: consolidate the "begin section" logic

Pull the repeated "begin a section" logic into a single place and hide it
within the KernelEntry class.

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

show more ...

docs: kdoc: Make body_with_blank_line parsing more flexible

The regex in the BODY_WITH_BLANK_LINE case was looking for lines starting
with " * ", where exactly one space was allowed before the follo

docs: kdoc: Make body_with_blank_line parsing more flexible

The regex in the BODY_WITH_BLANK_LINE case was looking for lines starting
with " * ", where exactly one space was allowed before the following text.
There are many kerneldoc comments where the authors have put multiple
spaces instead, leading to mis-formatting of the documentation.
Specifically, in this case, the description portion is associated with the
last of the parameters.

Allow multiple spaces in this context.

See, for example, synchronize_hardirq() and how its documentation is
formatted before and after the change.

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

show more ...

docs: kdoc: some final touches for process_name()

Add some comments to process_name() to cover its broad phases of operation,
and slightly restructure the if/then/else structure to remove some early

docs: kdoc: some final touches for process_name()

Add some comments to process_name() to cover its broad phases of operation,
and slightly restructure the if/then/else structure to remove some early
returns.

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

show more ...

docs: kdoc: move the declaration regexes out of process_name()

Move two complex regexes up with the other patterns, decluttering this
function and allowing the compilation to be done once rather tha

docs: kdoc: move the declaration regexes out of process_name()

Move two complex regexes up with the other patterns, decluttering this
function and allowing the compilation to be done once rather than for every
kerneldoc comment.

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

show more ...

docs: kdoc: remove some ineffective code

The code testing for a pointer declaration in process_name() has no actual
effect on subsequent actions; remove it.

Reviewed-by: Mauro Carvalho Chehab <mche

docs: kdoc: remove some ineffective code

The code testing for a pointer declaration in process_name() has no actual
effect on subsequent actions; remove it.

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

show more ...

docs: kdoc: remove the KernelEntry::descr pseudo member

The entry.descr value used in process_name() is not actually a member of
the KernelEntry class; it is a bit of local state. So just manage it

docs: kdoc: remove the KernelEntry::descr pseudo member

The entry.descr value used in process_name() is not actually a member of
the KernelEntry class; it is a bit of local state. So just manage it
locally.

A trim_whitespace() helper was added to clean up the code slightly.

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

show more ...

docs: kdoc: remove the KernelEntry::is_kernel_comment member

entry::is_kernel_comment never had anything to do with the entry itself; it
is a bit of local state in one branch of process_name(). It

docs: kdoc: remove the KernelEntry::is_kernel_comment member

entry::is_kernel_comment never had anything to do with the entry itself; it
is a bit of local state in one branch of process_name(). It can, in fact,
be removed entirely; rework the code slightly so that it is no longer
needed.

No change in the rendered output.

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

show more ...

docs: kdoc: simplify the kerneldoc recognition code

process_name() looks for the first line of a kerneldoc comment. It
contains two nearly identical regular expressions, the second of which only
ca

docs: kdoc: simplify the kerneldoc recognition code

process_name() looks for the first line of a kerneldoc comment. It
contains two nearly identical regular expressions, the second of which only
catches six cases in the kernel, all of the form:

define SOME_MACRO_NAME - description

Simply put the "define" into the regex and discard it, eliminating the loop
and the code to remove it specially.

Note that this still treats these defines as if they were functions, but
that's a separate issue.

There is no change in the generated output.

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

show more ...

docs: kdoc: remove the section_intro variable

It is only used in one place, so just put the constant string
"Introduction" there so people don't have to go looking for it.

Reviewed-by: Mauro Carval

docs: kdoc: remove the section_intro variable

It is only used in one place, so just put the constant string
"Introduction" there so people don't have to go looking for it.

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

show more ...

docs: kdoc: move the core dispatch into a state table

Since all of the handlers already nicely have the same prototype, put them
into a table and call them from there and take out the extended
if-th

docs: kdoc: move the core dispatch into a state table

Since all of the handlers already nicely have the same prototype, put them
into a table and call them from there and take out the extended
if-then-else series.

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

show more ...

docs: kdoc: simplify the PROTO continuation logic

Remove the unneeded "cont" variable and tighten up the code slightly.

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

docs: kdoc: simplify the PROTO continuation logic

Remove the unneeded "cont" variable and tighten up the code slightly.

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

show more ...

kernel-doc: Fix symbol matching for dropped suffixes

The support for dropping "_noprof" missed dropping the suffix from
exported symbols. That meant that using the :export: feature would
look for k

kernel-doc: Fix symbol matching for dropped suffixes

The support for dropping "_noprof" missed dropping the suffix from
exported symbols. That meant that using the :export: feature would
look for kernel-doc for (eg) krealloc_noprof() and not find the
kernel-doc for krealloc().

Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes)
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250606141543.1285671-1-willy@infradead.org

show more ...