[igt-dev] [PATCH i-g-t 1/1] scripts: add a parser to produce documentation from Kernel C file metatags

[Jani Nikula]

On Fri, 03 Feb 2023, Mauro Carvalho Chehab <mauro.chehab at linux.intel.com> wrote:
> From: Mauro Carvalho Chehab <mchehab at kernel.org>
>
> On a similar approach to Kernel's kernel-doc script, add a parser
> that will produce documentation from special-purpose documentation
> tags inside IGT tests.

kernel-doc is really not a great model to duplicate elsewhere.

Why hand craft another C parser? There's a cost to maintaining this, and
it's not helped by the choice of implementation language.

The script alone isn't enough; how do you bolt this into other
documentation? More ad hoc scripting like
docs/reference/igt-gpu-tools/{generate_description_xml.py,generate_programs_xml.sh}?

> Signed-off-by: Mauro Carvalho Chehab <mchehab at kernel.org>
> ---
>  scripts/igt-doc | 647 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 647 insertions(+)
>  create mode 100755 scripts/igt-doc
>
> diff --git a/scripts/igt-doc b/scripts/igt-doc
> new file mode 100755
> index 000000000000..3ed2be144e61
> --- /dev/null
> +++ b/scripts/igt-doc
> @@ -0,0 +1,647 @@
> +#!/usr/bin/env perl
> +# SPDX-License-Identifier: GPL-2.0

All of IGT is MIT, except the headers copied from kernel. Is this
GPL-2.0 because there's so much kernel-doc in it...

> +## Copyright (C) 2023    Intel Corporation                 ##
> +## Author: Mauro Carvalho Chehab <mchehab at kernel.org>      ##
> +## Inspired on Linux kernel-doc script                     ##

...

> +igt-doc - Print formatted kernel documentation to stdout
                             ^^^^^^

-- 
Jani Nikula, Intel Open Source Graphics Center