linux-kernel - Re: [PATCH v4] kernel.h: add comments for system

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20250908130824.7510ffda@foz.lan>
Date: Mon, 8 Sep 2025 13:08:24 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Randy Dunlap <rdunlap@...radead.org>, linux-kernel@...r.kernel.org,
 Andrew Morton <akpm@...ux-foundation.org>, Greg Kroah-Hartman
 <gregkh@...uxfoundation.org>, Pavel Machek <pavel@....cz>, Len Brown
 <len.brown@...el.com>, linux-pm@...r.kernel.org, Jonathan Corbet
 <corbet@....net>, linux-doc@...r.kernel.org, "James E.J. Bottomley"
 <James.Bottomley@...senpartnership.com>
Subject: Re: [PATCH v4] kernel.h: add comments for system_states

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

> On Sun, 07 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@...nel.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