Re: [PATCH v4 0/5] kernel-doc: add support for documenting vars

[Akira Yokosawa <akiyks@gmail.com>]

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