bybrooklyn/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-03 14:02:43 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc: better handle source when producing YAML output

Browse Source 
The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc markups are OK, on places where there is a "/**"
without a valid kernel-doc markup, it ends that the 1:1 match
between source code and KdocItem doesn't happen, causing
problems to generate the YAML output.

Fix it by storing the source code directly into the KdocItem
structure.

This shouldn't affect performance or memory footprint, except
when --yaml option is used.

While here, add a __repr__() function for KdocItem, as it
helps debugging it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <77902dafabb5c3250486aa2dc1568d5fafa95c5b.1774256269.git.mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2026-03-23 10:10:50 +01:00
committed by Jonathan Corbet
parent 8326e4a218
commit 99ec67a998
5 changed files with 79 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
tools/lib/python/kdoc/kdoc_yaml_file.py
View File

@@ -85,7 +85,7 @@ class KDocTestFile():
return d
def output_symbols(self, fname, symbols, source):
def output_symbols(self, fname, symbols):
"""
Store source, symbols and output strings at self.tests.
"""
@@ -96,16 +96,10 @@ class KDocTestFile():
kdoc_item = []
expected = []
if not symbols and not source:
return
if not source or len(symbols) != len(source):
print(f"Warning: lengths are different. Ignoring {fname}")
# Folding without line numbers is too hard.
# The right thing to do here to proceed would be to delete
# not-handled source blocks, as len(source) should be bigger
# than len(symbols)
#
# Source code didn't produce any symbol
#
if not symbols:
return
base_name = "test_" + fname.replace(".", "_").replace("/", "_")
@@ -115,9 +109,15 @@ class KDocTestFile():
for i in range(0, len(symbols)):
arg = symbols[i]
if "KdocItem" in self.yaml_content:
source = arg.get("source", "")
if arg and "KdocItem" in self.yaml_content:
msg = self.get_kdoc_item(arg)
other_stuff = msg.get("other_stuff", {})
if "source" in other_stuff:
del other_stuff["source"]
expected_dict["kdoc_item"] = msg
for out_style in self.out_style:
@@ -132,9 +132,9 @@ class KDocTestFile():
test = {
"name": name,
"description": f"{fname} line {source[i]["ln"]}",
"description": f"{fname} line {arg.declaration_start_line}",
"fname": fname,
"source": source[i]["data"],
"source": source,
"expected": [expected_dict]
}