bybrooklyn/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-04-28 11:32:28 -04:00
Code Issues Packages Projects Releases Wiki Activity

kernel-doc: add support for handling global variables

Browse Source 
Specially on kAPI, sometimes it is desirable to be able to
describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need
to parse a data struct. All we need is the variable
declaration and use native C domain ::c:var: to format it
for us.

Add support for it.

Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c09@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <fa7d1c61a8de9150f71b318382f1507d3b13848d.1765894964.git.mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2025-12-16 15:26:12 +01:00
committed by Jonathan Corbet
parent 82e87387f6
commit 1045ec382c
2 changed files with 102 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
tools/lib/python/kdoc/kdoc_parser.py
View File

@@ -64,7 +64,7 @@ type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
# Tests for the beginning of a kerneldoc block in its various forms.
#
doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)", cache = False)
doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|var)\b\s*(\w*)", cache = False)
doc_begin_func = KernRe(str(doc_com) + # initial " * '
r"(?:\w+\s*\*\s*)?" + # type (not captured)
r'(?:define\s+)?' + # possible "define" (not captured)
@@ -927,6 +927,58 @@ class KernelDoc:
self.output_declaration('enum', declaration_name,
purpose=self.entry.declaration_purpose)
def dump_var(self, ln, proto):
"""
Store variables that are part of kAPI.
"""
VAR_ATTRIBS = [
"extern",
]
OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?"
sub_prefixes = [
(KernRe(r"__read_mostly"), ""),
(KernRe(r"__ro_after_init"), ""),
(KernRe(r"(?://.*)$"), ""),
(KernRe(r"(?:/\*.*\*/)"), ""),
(KernRe(r";$"), ""),
(KernRe(r"=.*"), ""),
]
#
# Store the full prototype before modifying it
#
full_proto = proto
#
# Drop comments and macros to have a pure C prototype
#
for search, sub in sub_prefixes:
proto = search.sub(sub, proto)
proto = proto.rstrip()
#
# Variable name is at the end of the declaration
#
r= KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
if not r.match(proto):
self.emit_msg(ln,f"{proto}: can't parse variable")
return
var_type = r.group(0)
declaration_name = r.group(1)
default_val = r.group(2)
if default_val:
default_val = default_val.lstrip("=").strip()
self.output_declaration("var", declaration_name,
full_proto=full_proto,
var_type=var_type,
default_val=default_val,
purpose=self.entry.declaration_purpose)
def dump_declaration(self, ln, prototype):
"""
Stores a data declaration inside self.entries array.
@@ -938,6 +990,8 @@ class KernelDoc:
self.dump_typedef(ln, prototype)
elif self.entry.decl_type in ["union", "struct"]:
self.dump_struct(ln, prototype)
elif self.entry.decl_type == "var":
self.dump_var(ln, prototype)
else:
# This would be a bug
self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')