docs: kdoc: split the processing of the two remaining inline states

Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditiona

docs: kdoc: split the processing of the two remaining inline states

Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.

The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.

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

show more ...

docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
subs

docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.

INLINE_ERROR was never actually used for anything, so just take it out.

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/20250627184000.132291-8-corbet@lwn.net

show more ...

docs: kdoc: remove the INLINE_END state

It is never used, so just get rid of it.

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

docs: kdoc: remove the INLINE_END state

It is never used, so just get rid of it.

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

show more ...

docs: kdoc: rework process_export() slightly

Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state

docs: kdoc: rework process_export() slightly

Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.

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

show more ...

docs: kdoc: remove KernelEntry::function

This member is unused, to take it out.

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

docs: kdoc: remove KernelEntry::function

This member is unused, to take it out.

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

show more ...

docs: kdoc: remove a bit of dead code

The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just remove it.

Reviewed-by: Mauro Car

docs: kdoc: remove a bit of dead code

The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just 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/20250627184000.132291-4-corbet@lwn.net

show more ...

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.

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

show more ...

docs: kdoc: remove KernelEntry::in_doc_sect

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

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

docs: kdoc: remove KernelEntry::in_doc_sect

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

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

show more ...

docs: kdoc: remove the brcount floor in process_proto_type()

Putting the floor under brcount does not change the output in any way, just
remove it.

Change the termination test from ==0 to <=0 to pr

docs: kdoc: remove the brcount floor in process_proto_type()

Putting the floor under brcount does not change the output in any way, just
remove it.

Change the termination test from ==0 to <=0 to prevent infinite loops in
case somebody does something truly wacko in the code.

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

show more ...

docs: kdoc: micro-optimize KernRe

Switch KernRe::add_regex() to a try..except block to avoid looking up each
regex twice.

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

docs: kdoc: don't reinvent string.strip()

process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just

docs: kdoc: don't reinvent string.strip()

process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just use strip().

The previous implementation also (in process_proto_type()) removed C++
comments *after* the above dance, leaving trailing whitespace in that case;
now we do the stripping afterward. This results in exactly one output
change: the removal of a spurious space in the definition of
BACKLIGHT_POWER_REDUCED - see
https://docs.kernel.org/gpu/backlight.html#c.backlight_properties.

I note that we are putting semicolons after #define lines that really
shouldn't be there - a task for another day.

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

show more ...

docs: kdoc: split the processing of the two remaining inline states

Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditiona

docs: kdoc: split the processing of the two remaining inline states

Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.

The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.

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

show more ...

docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
subs

docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.

INLINE_ERROR was never actually used for anything, so just take it out.

No changes to the generated output.

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

show more ...

docs: kdoc: remove the INLINE_END state

It is never used, so just get rid of it.

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

docs: kdoc: rework process_export() slightly

Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state

docs: kdoc: rework process_export() slightly

Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.

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

show more ...

docs: kdoc: remove KernelEntry::function

This member is unused, to take it out.

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

docs: kdoc: remove a bit of dead code

The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just remove it.

Signed-off-by: Jonatha

docs: kdoc: remove a bit of dead code

The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just remove it.

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

show more ...

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 ...