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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Mon, 08 Sep 2025 12:22:06 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

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

Good idea. We need to verify first if :param: and :returns: are available 
since 3.4.3. Docs imply so:

	https://www.sphinx-doc.org/en/master/usage/domains/c.html

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

We still need to parse all parameters, as we need them for man pages, as this
is the standard practice (see "man 2 read", for instance).

We may do something else for html, but:

- on functions, the full prototype is required by Sphinx:

	.. c:function:: void media_set_bus_info (char *bus_info, size_t bus_info_size, struct device *dev)

- for struct/union/enum, a data type is not supported, but the documentation
  has an example about how Sphinx actually expects it:

	.. c:struct:: Data

	   .. c:union:: @data

	      .. c:var:: int a

	      .. c:var:: double b

  If we're willing to use the Sphinx way, tests are required.
  Implementing it would add more complexity, though. Not sure
  about the benefits if any.

In summary, for html/pdf/epub, there are three possible outcomings:

- keep as-is;
- replace them by links;
- implement Sphinx way.

In any case, changing it won't cleanup the code, as we still need
parameters parsing for man pages.

Also, as a documentation user, when read I documentation, I do 
expect to see the function prototypes just before parameter
descriptions. If possible, untouched. This is specially important, 
IMHO, where there are macros to help generating functions and structs.

Thanks,
Mauro