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 fb7e03805a11..f0a6659797b3 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.47.3

Oleksij Rempel <o.rempel@pengutronix.de> writes:

> 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 fb7e03805a11..f0a6659797b3 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)}"

It seems potentially misleading to emit "enum attr-set-name" since they
are anonymous enums.

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