diff -u b/core/core.api.php b/core/core.api.php
--- b/core/core.api.php
+++ b/core/core.api.php
@@ -1125,11 +1125,13 @@
  *   @group annotation, which gives information about the test.
  * - For unit tests, this comment block should also have @coversDefaultClass
  *   annotation.
- * - Test cases within your class are public methods with names that
- *   start with 'test' and have no arguments; for example, testYourTestCase().
- *   For unit tests, you can also use @covers and @dataProvider annotation
- *   to indicate a test method.
- * - Each test case method should test a logical subset of the functionality.
+ * - When writing tests, put the test code into public methods, each covering a
+ *   logical subset of the functionality that is being tested.
+ * - For unit and kernel tests, the test methods need to have a phpDoc block
+ *   with @covers annotation telling which class method they are testing, and
+ *   usually use a data provider method, given in @dataProvider annotation.
+ * - For browser tests, the test methods have names starting with 'test' and
+ *   have no arguments.
  * - In some cases, you may need to write a test module to support your test;
  *   put such modules under the yourmodule/tests/modules directory.
  *