[Intel-gfx] [PATCH i-g-t 1/2] Add support for subtest-specific documentation

[Arkadiusz Hiler]

On Wed, Aug 09, 2017 at 02:40:49PM +0300, Petri Latvala wrote:
> The current documentation for tests is limited to a single string per
> test binary. This patch adds support for documenting individual
> subtests.
> 
> The syntax for subtest documentation is:
> 
>    igt_document_subtest("Frob knobs to see if one of the "
>                         "crossbeams will go out of skew on the "
>                         "treadle.\n");
>    igt_subtest("knob-frobbing-askew")
>      test_frob();
> 
> or with a format string:
> 
>   for_example_loop(e) {
>     igt_document_subtest_f("Frob %s to see if one of the "
>                            "crossbeams will go out of skew on the "
>                            "treadle.\n", e->readable_name);
>     igt_subtest_f("%s-frob-askew", e->name)
>       test_frob(e);
>   }
> 
> The documentation cannot be extracted from just comments, because
> associating them with the correct subtest name will then require doing
> pattern matching in the documentation generator, for subtests where
> the name is generated at runtime using igt_subtest_f.
> 
> v2: Rebase, change function name in commit message to match code
> 
> Signed-off-by: Petri Latvala <petri.latvala at intel.com>
> Acked-by: Leo Li <sunpeng.li at amd.com>

I like approach of pairing the documentation 1:1 with subtests much
better than just having comments on top of internal functions (those
does not have to map directly onto subtests).

Bonus points for having it right above the igt_subtest_f() call and
making it easily accessible from the command line as those are the two
places developers and maintainers check first.

Acked-by: Arkadiusz Hiler <arkadiusz.hiler at intel.com>