Re: [PATCH v4] kernel.h: add comments for system_states

[Jani Nikula <jani.nikula@linux.intel.com>]

On Sun, 07 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> Heh, looking at Sphinx doc at:
> https://www.sphinx-doc.org/en/master/usage/domains/c.html:
>
> 	.. c:member:: declaration
> 	.. c:var:: declaration
>
> 	    Describes a C struct member or variable. Example signature:
>
> 	    .. c:member:: PyObject *PyTypeObject.tp_bases
>
> 	    The difference between the two directives is only cosmetic.
>
> I guess the best is to encode it as:
>
> 	prototype = args.other_stuff["var_type"]
> 	self.data += f"\n\n.. c:var:: {prototype}\n\n"
>
> And let Sphinx format it for us.

In the same vein, I believe we should let Sphinx format everything else
for us as well. Function parameters should use ":param foo: desc" and
struct/union members should be indented within the enclosing
struct/union.

I also think we're going way overboard with including e.g. struct
definition in the output. I'd just chuck those away and maybe add links
to kernel git source for the definition instead.


BR,
Jani.


-- 
Jani Nikula, Intel