[Intel-gfx] [RFC i-g-t] tests/gem_exec_basic: Documentation for subtests

[Arkadiusz Hiler]

On Tue, Aug 08, 2017 at 03:09:00PM -0700, Vinay Belgaumkar wrote:
> This is an RFC for adding documentation to IGT subtests. Each subtest can have
> something similar to a WHAT - explaining what the subtest actually does,
> and a WHY - which explains a use case, if applicable. Additionally,
> include comments for anything in the subtest code which can help
> explain HOW the test has been implemented. We don't actually need the WHAT
> and WHY tags in the documentation.
> 
> These comments will not be linked to gtkdoc as of now, since we do not have a
>  mechanism to link it to every subtest name.

Hey Vinay,

I get similar feelings towards this RFC as Lukasz and Radek do.

Was your intention to propose format of the comments? Or maybe force
people to comment more on the code? Or just pointing out that we could
use some subtest documentation?

You are not documenting subtests, you are documenting arbitrary
functions that may or may not be used as a subtest.

I cannot help but feel lost here.

Being explicit as of your intention and coming up with more abstract or
better examples would also help, as current ones are detracting from the
idea itself.

I do not get this RFC and it's purpose but I am looking forward to
seeing revised version that is clearer on your intentions and easier to
grasp.

-- 
Cheers,
Arek