It has become sort of a de-facto standard to have no phpdocs on test methods in Moodle phpunit tests.

I am fine with this because:

• I think the test name should be the descriptive part - as it also is the most commonly shared part of the failure
• I've seen when people add extensive phpdoc blocks that they easily get outdated as someone adds another few assertions to address whats going on
• I like this style of commenting for tests:

  function test_foobar_baz_is_a_bad_example() {

  // Explain exactly what test data i'm setting up.

  $foo = new foo();

  // Execute the code.

  $baz = $foo->bar();

  // Now explain each assertion on that test data inline.

  $this->assertTrue($baz);

  }

With this in mind, I propose we make an exception for phpdoc blocks on test methods.