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@xxxxxxxxx> Signed-off-by: Petri Latvala <petri.latvala@xxxxxxxxx> ## 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 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
