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

[Jonathan Corbet <corbet@lwn.net>]

Mauro Carvalho Chehab <mchehab+huawei@kernel.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