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

[Daniel Vetter]

On Fri, 3 Feb 2023 at 11:24, Jani Nikula <jani.nikula at linux.intel.com> wrote:
>
> 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.

Yes.

Like just "yes".

Also quite frankly I think a large chunk of the problem many igts have
(especially in the i915-gem area) is not the lacking documentation.
-Daniel

> 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



-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch