[igt-dev] [PATCH i-g-t v3 0/1] Add a script to allow inlined test documentation

[Lucas De Marchi]

On Tue, Feb 14, 2023 at 01:35:29PM +0100, Mauro Carvalho Chehab wrote:
>From: Mauro Carvalho Chehab <mchehab at kernel.org>
>
>Keeping documentation updated is hard, as text documents gets outdated
>when code changes. The best practices are to keep documentation as close
>as possible to the code.
>
>This script allows adding documentation inside special tags at the
>C files, and validate if the documentation actually meets the code.
>
>It is meant to be used by the new Intel Xe driver, in the process of
>being upstreamed. It can be used also for other drivers, as well.
>
>It supports three modes of operation:
>
>1) Output documentation in ReST format (default if no arg provided):
>
>	$ scripts/igt-doc.py --files tests/xe/*.c --rest
>
>2) Output a list of tests that are documented
>
>	$ scripts/igt-doc.py --files tests/xe/*.c --show-subtests
>
>3) Compare the documented testlists with IGT runner testlist:
>
>	$ scripts/igt-doc.py --files tests/xe/*.c --check-testlist
>
>The idea is to add automation to generate the ReST files at the
>Xe meson.build file. Once all documentation for Xe is placed inline,
>the CI for it can also use this script to discover documentation
>gaps.


once upon a time there was the initiative to document the tests and the
decision was also to encode this information close to the tests. AFAIK
then we got lib/tests/igt_describe.c and testst to be documented with
IGT_TEST_DESCRIPTION().  Main reason I believe was that it's then also
possible to know what the test is doing by running the test itself.
Was extending that considered?  There is even
.gitlab-ci.yml:test:list-undocumented-tests

>
>Both modes (1) and (2) can be tested by running:
>
>	$ ./scripts/igt_doc.py --files ./scripts/igt_doc.py
>
>This will use the strings inside the class docstring added on version
>3, parsing them as if they're C file documentatoin.

If using comments is the way to go now, I don't have any issue with
that. But we probably need to convert the old documentation to the new
one. Also, to cover the gap that the binary is not self-documented
anymore, could we  run this script to create a blob and then call
objcopy to glue it together with the test binary? This way --describe
would continue to work.


Lucas De Marchi