[igt-dev] [ANNOUNCEMENT] Documenting tests with igt_describe()

[Arkadiusz Hiler]

Hey all,

IGT tests are largely undocumented and a lot of them are quite enigmatic if you
haven't internalized the whole framework and are not familiar with naming
conventions that some people use.

To tackle this we require[0] documenting new tests with igt_describe()[1].

The idea is to provide a short description (one or two sentences) on
what the test is supposed to verify to give the reader enough of context
so they easily can tell what scenario the test is exercising.

This also makes reading the tests so much easier - sometimes it is
really hard and takes a long time to understand the main thought behind
a test just from the implementation details.

We don't want you to translate C into English, we want you to provide a bit of
that extra information that you would have put in the comments anyway.

See igt_describe() documentation[1] for guidelines on writing good descriptions.

[0]: https://gitlab.freedesktop.org/drm/igt-gpu-tools/blob/master/CONTRIBUTING.md#L19
[1]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html#igt-describe

Signed-off-by: Arkadiusz Hiler <arkadiusz.hiler at intel.com>
Signed-off-by: Petri Latvala <petri.latvala at intel.com>


## FAQ

Q: How is this being enforced?
A: If your patch introduces undocumented tests you will get an email with
   instruction how to proceed. This is considered as failing the CI checks.
   e.g.: https://lists.freedesktop.org/archives/igt-dev/2019-November/017266.html

Q: I am not sure my descriptions are good...
A: That what the review is for. Feel free to poke me or Petri on IRC in case you
   want some help with writing them.

Q: Why are you using igt_describe() and not doxygen/sphinx/gtk-doc/etc.
   comments?
A: We are documenting tests, not C functions. Those tools do not
   understand comments over magic control blocks used by the test
   harness to define tests/subtests. Additional benefit is that the
   documentation is available not only in the source code and the
   generated documentation but also on the command line by using
   --describe switch.

-- 
Cheers,
Arek