linux-kernel - Re: [PATCH v4 0/5] 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] [thread-next>] [day] [month] [year] [list]

Message-ID: <dc0540b6-4f48-4d06-b68e-c4cb8be7a52e@gmail.com>
Date: Sun, 23 Nov 2025 20:28:23 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: mchehab+huawei@...nel.org
Cc: corbet@....net, linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
 mchehab@...nel.org, rdunlap@...radead.org
Subject: Re: [PATCH v4 0/5] kernel-doc: add support for documenting vars

Hi Mauro,

On Sat, 22 Nov 2025 13:37:54 +0100, Mauro Carvalho Chehab wrote:
> Hi Jon,
> 
> As suggested and discussed with Randy, this small series add support
> for documenting variables using kernel-doc.
> 
> - patch 1: add support for the new feature;
> - patch 2: extends to support DEFINE_*;
> - patch 3: document two media vars;
> - patch 4: fix an issue on kernel-doc.rst markups and automarkup;
> - patch 5: document it.
> 
> On this version, I'm using "c:macro" to describe variables, as it
> avoids Sphinx C domain to try parse the variable. This makes it more
> flexible and easier to maintain in long term.

In my test on top of current docs-next, I got two *new* warnings from
"make cleandocs; make htmldocs":

    .../Documentation/driver-api/media/v4l2-common:8: ../include/media/v4l2-ioctl.h:665: WARNING: Inline emphasis start-string without end-string. [docutils]
    .../Documentation/driver-api/media/v4l2-common:8: ../include/media/v4l2-ioctl.h:678: WARNING: Inline emphasis start-string without end-string. [docutils]

"scripts/kernel-doc -rst include/media/v4l2-ioctl.h" emits the following:

    .. c:macro:: v4l2_field_names

=>    extern const char *v4l2_field_names[];

      Helper array mapping V4L2_FIELD_* to strings.

      **Description**

      Specially when printing debug messages, it is interesting to output
      the field order at the V4L2 buffers. This array associates all possible
      values of field pix format from V4L2 API into a string.




    .. c:macro:: v4l2_type_names

=>    extern const char *v4l2_type_names[];

      Helper array mapping V4L2_BUF_TYPE_* to strings.

      **Description**

      When printing debug messages, it is interesting to output the V4L2 buffer
      type number with a name that represents its content.

I think those declaration signatures need to be inline-literal. 

Thanks, Akira

> 
> ---
> 
> v4: 
> - document the new markup;
> - fix an issue on kernel-doc.rst due to automarkup;
> - add support for DEFINE_* macros
> 
> Mauro Carvalho Chehab (5):
>   kernel-doc: add support for handling global variables
>   kernel-doc: add support to handle DEFINE_ variables
>   docs: media: v4l2-ioctl.h: document two global variables
>   docs: kernel-doc.rst: don't let automarkup mangle with consts
>   docs: kernel-doc.rst: document the new "var" kernel-doc markup
> 
>  Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++------
>  include/media/v4l2-ioctl.h             | 15 ++++++
>  tools/lib/python/kdoc/kdoc_output.py   | 46 ++++++++++++++++
>  tools/lib/python/kdoc/kdoc_parser.py   | 73 +++++++++++++++++++++++++-
>  4 files changed, 166 insertions(+), 16 deletions(-)
> 
> -- 
> 2.51.1