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] [thread-next>] [day] [month] [year] [list]

Message-ID: <f6e0f7409df67e0554885cacb74023a8aad9a717@intel.com>
Date: Mon, 08 Sep 2025 12:22:06 +0300
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Randy Dunlap
 <rdunlap@...radead.org>
Cc: 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

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.

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