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.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-4-corbet@lwn.net

show more ...

docs: kdoc: micro-optimize KernRe

Rework _add_regex() to avoid doing the lookup twice for the (hopefully
common) cache-hit case.

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

docs: kdoc: micro-optimize KernRe

Rework _add_regex() to avoid doing the lookup twice for the (hopefully
common) cache-hit case.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-3-corbet@lwn.net

show more ...

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.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-2-corbet@lwn.net

show more ...

docs: kdoc: simplify the output-item passing

Since our output items contain their name, we don't need to pass it
separately.

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

docs: kdoc: simplify the output-item passing

Since our output items contain their name, we don't need to pass it
separately.

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

show more ...

docs: kdoc; Add a rudimentary class to represent output items

This class is intended to replace the unstructured dict used to accumulate
an entry to pass to an output module. For now, it remains un

docs: kdoc; Add a rudimentary class to represent output items

This class is intended to replace the unstructured dict used to accumulate
an entry to pass to an output module. For now, it remains unstructured,
but it works well enough that the output classes don't notice the
difference.

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

show more ...

docs: kdoc: pretty up dump_enum()

Add some comments to dump_enum to help the next person who has to figure
out what it is actually doing.

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

docs: kdoc: some tweaks to process_proto_function()

Add a set of comments to process_proto_function and reorganize the logic
slightly; no functional change.

Signed-off-by: Jonathan Corbet <corbet@l

docs: kdoc: some tweaks to process_proto_function()

Add a set of comments to process_proto_function and reorganize the logic
slightly; no functional change.

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

show more ...

docs: kdoc: rework type prototype parsing

process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a

docs: kdoc: rework type prototype parsing

process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a simpler regex to just do the split directly, and handle each chunk
as it comes. The result is, IMO, easier to understand and reason about.

The old algorithm would occasionally elide the space between function
parameters; see struct rng_alg->generate(), foe example. The only output
difference is to not elide that space, which is more correct.

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.

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