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

[Belgaumkar, Vinay]

On 8/9/2017 7:32 AM, Arkadiusz Hiler wrote:
> 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.
>

Hi Arek,
      The purpose of this RFC is to complement Petri's subtest 
documentation patch. That patch will give us
an ability to add a line of documentation per subtest, which is 
definitely useful. However, what I noticed is
that when you actually start debugging a test issue and step into the 
subtest code, it is very hard to understand
what the purpose of certain commands are. My intention was to provide a 
text only documentation in the test source
to allow test developers to understand the code better. It's hard to 
explain the how and and why all in a single sentence.

If we provided an ability/guideline to test developers for mentioning 
the same at the beginning of the actual subtest code,
it can make debugging a lot more simpler rather than having to jump back 
to the main function to figure out what the subtest
is supposed to do. I have also included some comments inside the test 
function to explain why we use certain system calls.
Idea was not to define the system call, but explain why it is being used.

Again, I did not mean to duplicate the subtest documentation effort. My 
initial plan was to send out an
RFC using Petri's patch as well, so that the intention is more clear. I 
can do that with the second version of the patch if needed.
However, the main aim is to agree on a convention to add more 
documentation to the subtest code so that it simplifies
debugging and helps with understanding of the aim behind writing the 
particular subtest.