Parse 'doc' strings from the YAML spec to generate kernel-doc comments
for the corresponding enums in the C UAPI header, making the headers
self-documenting.
The generated comment format depends on the documentation available:
- a full kdoc block ('/**') with @member tags is used if attributes are
documented
- a simple block comment ('/*') is used if only the set itself has a doc
string
Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
tools/net/ynl/pyynl/ynl_gen_c.py | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/tools/net/ynl/pyynl/ynl_gen_c.py b/tools/net/ynl/pyynl/ynl_gen_c.py
index ef032e17fec4..d7634560c461 100755
--- a/tools/net/ynl/pyynl/ynl_gen_c.py
+++ b/tools/net/ynl/pyynl/ynl_gen_c.py
@@ -3225,6 +3225,29 @@ def render_uapi(family, cw):
if attr_set.subset_of:
continue
+ # Write kdoc for attribute-set enums
+ has_main_doc = 'doc' in attr_set.yaml and attr_set.yaml['doc']
+ has_attr_doc = any('doc' in attr for _, attr in attr_set.items())
+
+ if has_main_doc or has_attr_doc:
+ if has_attr_doc:
+ cw.p('/**')
+ # Construct the main description line for the enum
+ doc_line = f"enum {c_lower(family.ident_name + '_' + attr_set.name)}"
+ if has_main_doc:
+ doc_line += f" - {attr_set.yaml['doc']}"
+ cw.write_doc_line(doc_line)
+
+ # Write documentation for each attribute (enum member)
+ for _, attr in attr_set.items():
+ if 'doc' in attr and attr['doc']:
+ doc = f"@{attr.enum_name}: {attr['doc']}"
+ cw.write_doc_line(doc)
+ else: # Only has main doc, use a simpler comment block
+ cw.p('/*')
+ cw.write_doc_line(attr_set.yaml['doc'], indent=False)
+ cw.p(' */')
+
max_value = f"({attr_set.cnt_name} - 1)"
val = 0
--
2.39.5