linux-kernel - Re: [PATCH v3 0/2] kernel-doc: add support for documenting vars

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: <87bjkvtgum.fsf@trenco.lwn.net>
Date: Fri, 21 Nov 2025 10:50:41 -0700
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Linux Doc Mailing
 List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Mauro Carvalho Chehab
 <mchehab@...nel.org>, linux-kernel@...r.kernel.org, Randy Dunlap
 <rdunlap@...radead.org>
Subject: Re: [PATCH v3 0/2] kernel-doc: add support for documenting vars

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> Hi Jon,
>
> As suggested and discussed with Randy, this small series add support
> for documenting variables using kernel-doc.
>
> The first patch adds support for it.
> The second one documents two variables from media. 
>
> While two documented variables are part of kAPI, I'm documenting them
> mostly aiming to test the new feature, as those are meant to be used for
> debugging messages, so we could live without having them documented.
>
> I'm pretty sure we'll likely need to improve the parser regexes to
> catch everything. For instance, I had to add a logic on v3 due to the
> choice I did for the vars, which are pointers.
>
> Mauro Carvalho Chehab (2):
>   kernel-doc: add support for handling global variables
>   docs: media: v4l2-ioctl.h: document two global variables
>
>  include/media/v4l2-ioctl.h      | 15 +++++++++
>  scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
>  scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
>  3 files changed, 115 insertions(+), 1 deletion(-)

This all seems fine at a first glance ... except I'm missing the update
to Documentation/doc-guide/kernel-doc.rst.  If we don't document the
documentation system, our moral position when we fault others for not
using it is ... weak ... :)

Thanks,

jon