f587722a | 15-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
Merge branch 'kdoc-item2' into docs-mw
The kerneldoc parsing phase gathers all of the information about the declarations of interest, then passes it through to the output phase as a dict that is an
Merge branch 'kdoc-item2' into docs-mw
The kerneldoc parsing phase gathers all of the information about the declarations of interest, then passes it through to the output phase as a dict that is an unstructured blob of information; this organization has its origins in the Perl version of the program. It results in an interface that is difficult to reason about, dozen-parameter function calls, and other ills.
Introduce a new class (KdocItem) to carry this information between the parser and the output modules, and, step by step, modify the system to use this class in a more structured way. This could be taken further by creating a subclass of KdocItem for each declaration type (function, struct, ...), but that is probably more structure than we need.
The result is (I hope) clearer code, the removal of a bunch of boilerplate, and no changes to the generated output.
show more ...
|
40020fe8 | 11-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: emit a warning for ancient versions of Python
Versions of Python prior to 3.7 do not guarantee to remember the insertion order of dicts; since kernel-doc depends on that guarantee, runni
docs: kdoc: emit a warning for ancient versions of Python
Versions of Python prior to 3.7 do not guarantee to remember the insertion order of dicts; since kernel-doc depends on that guarantee, running with such older versions could result in output with reordered sections.
Python 3.9 is the minimum for the kernel as a whole, so this should not be a problem, but put in a warning just in case somebody tries to use something older.
Suggested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
636d4d9e | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: clean up check_sections()
entry.sectcheck is just a duplicate of our list of sections that is only passed to check_sections(); its main purpose seems to be to avoid checking the special
docs: kdoc: clean up check_sections()
entry.sectcheck is just a duplicate of our list of sections that is only passed to check_sections(); its main purpose seems to be to avoid checking the special named sections. Rework check_sections() to not use that field (which is then deleted), tocheck for the known sections directly, and tighten up the logic in general.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
bd5628bf | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: directly access the always-there KdocItem fields
They are part of the interface, so use them directly. This allows the removal of the transitional __dict__ hack in KdocItem.
Reviewed-b
docs: kdoc: directly access the always-there KdocItem fields
They are part of the interface, so use them directly. This allows the removal of the transitional __dict__ hack in KdocItem.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
08b8dc43 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: straighten up dump_declaration()
Get rid of the excess "return" statements in dump_declaration(), along with a line of never-executed dead code.
Reviewed-by: Mauro Carvalho Chehab <mche
docs: kdoc: straighten up dump_declaration()
Get rid of the excess "return" statements in dump_declaration(), along with a line of never-executed dead code.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
a0db2051 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: Regularize the use of the declaration name
Each declaration type passes through the name in a unique field of the "args" blob - even though we have always just passed the name separately
docs: kdoc: Regularize the use of the declaration name
Each declaration type passes through the name in a unique field of the "args" blob - even though we have always just passed the name separately. Get rid of all the weird names and just use the common version.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
de6f7ac9 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: Coalesce parameter-list handling
Callers to output_declaration() always pass the parameter information from self.entry; remove all of the boilerplate arguments and just get at that infor
docs: kdoc: Coalesce parameter-list handling
Callers to output_declaration() always pass the parameter information from self.entry; remove all of the boilerplate arguments and just get at that information directly. Formalize its placement in the KdocItem class.
It would be nice to get rid of parameterlist as well, but that has the effect of reordering the output of function parameters and struct fields to match the order in the kerneldoc comment rather than in the declaration. One could argue about which is more correct, but the ordering has been left unchanged for now.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
efacdf85 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: use self.entry.parameterlist directly in check_sections()
Callers of check_sections() join parameterlist into a single string, which is then immediately split back into the original list
docs: kdoc: use self.entry.parameterlist directly in check_sections()
Callers of check_sections() join parameterlist into a single string, which is then immediately split back into the original list. Rather than do all that, just use parameterlist directly in check_sections().
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
172bee33 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: remove the "struct_actual" machinery
The code goes out of its way to create a special list of parameters in entry.struct_actual that is just like entry.parameterlist, but with extra junk
docs: kdoc: remove the "struct_actual" machinery
The code goes out of its way to create a special list of parameters in entry.struct_actual that is just like entry.parameterlist, but with extra junk. The only use of that information, in check_sections(), promptly strips all the extra junk back out. Drop all that extra work and just use parameterlist.
No output changes.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
8d733875 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: Centralize handling of the item section list
The section list always comes directly from the under-construction entry and is used uniformly. Formalize section handling in the KdocItem c
docs: kdoc: Centralize handling of the item section list
The section list always comes directly from the under-construction entry and is used uniformly. Formalize section handling in the KdocItem class, and have output_declaration() load the sections directly from the entry, eliminating a lot of duplicated, verbose parameters.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
8d9d1229 | 02-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: drop "sectionlist"
Python dicts (as of 3.7) are guaranteed to remember the insertion order of items, so we do not need a separate list for that purpose. Drop the per-entry sectionlist v
docs: kdoc: drop "sectionlist"
Python dicts (as of 3.7) are guaranteed to remember the insertion order of items, so we do not need a separate list for that purpose. Drop the per-entry sectionlist variable and just rely on native dict ordering.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
|
5d77dcc0 | 03-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.o
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.
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-8-corbet@lwn.net
show more ...
|
414ccf92 | 03-Jul-2025 |
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.
Reviewed-by: Mauro Carvalho Chehab <mche
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.
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-6-corbet@lwn.net
show more ...
|
b8ac0259 | 03-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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.
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-5-corbet@lwn.net
show more ...
|
061a1c1a | 03-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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 ...
|
8078e0ed | 03-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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 ...
|
703f9074 | 01-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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 ...
|
60016e01 | 01-Jul-2025 |
Jonathan Corbet <corbet@lwn.net> |
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 ...
|
901f5069 | 30-Jun-2025 |
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 ...
|
1aeb8099 | 30-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
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 ...
|