[igt-dev] [PATCH i-g-t 0/1] Add a script to document IGT tests

[Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>]

From: Mauro Carvalho Chehab <mchehab@kernel.org>

As the IGT and driver's code evolves, the meaning of the tests may
become unclear. The best way to avoid bitrot is to have in-code
documentation explaining what each test and subtest does.

This script adds support for in-code documentation placed on
a style similar to kernel-doc, e. g. it should parse test descriptions
like:

/**
 * TEST: Check if new IGT test documentation logic functionality is working
 * Category: Software build block
 * Sub-category: documentation
 * Coverered functionality: test documentation
 * Test type: ReST generation
 * Run type: IGT kunit test
 * Issue: none
 * Platforms: all
 * Platform requirements: none
 * Depends on: @igt@deadbeef@basic
 * Requirements: Need at least a script to test it
 * Description: Complete description of this test
 *
 * SUBTEST: foo
 * Description: do foo things
 * 	with description continuing on another line
 *
 * SUBTEST: bar
 * Description: do bar things
 * 	with description continuing on another line
 */

/**
 * SUBTEST: test-%s-binds-%s-with-%ld-size
 * Description: Test arg[2] arg[1] binds with arg[3] size
 *
 * arg[1]:
 *
 * @large:	large
 * 		something
 * @mixed:	mixed
 * 		something
 * @small:	small
 * 		something
 *
 * arg[2]:
 *
 * @binds:			foo
 * @misaligned-binds:		misaligned
 * @userptr-binds:		userptr
 * @userptr-misaligned-binds:	userptr misaligned
 *
 * arg[3]:	buffer size
 * 		in Kb
 */

Please notice that I'm sending this script in advance, in order to
have some upstream review. Such script currently is capable of
describing igt tests and IGT subtests, with wildcard support.

It is not currently prepared to handle dynamic subtests, nor to
describe Kernel selftest/KUnit. For those, it is probably worth
to have the documentation inside the Kernel, to keep them as close
as possible to the actual code.

The end goal is to use such script to describe the test bench for
the new Xe driver, auto-generating documentation. The Xe IGT upstream
work can be seen at https://patchwork.freedesktop.org/series/112191/.

Mauro Carvalho Chehab (1):
  scripts: add a parser to produce documentation from Kernel C file
    metatags

 scripts/igt-doc | 647 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 647 insertions(+)
 create mode 100755 scripts/igt-doc

-- 
2.39.0