docs

1 files changed, 12 insertions, 1 deletions

diff --git a/src/main/scala/org/perl8/test/Test.scala b/src/main/scala/org/perl8/test/Test.scala
index b877a3f..436719c 100644
--- a/src/main/scala/org/perl8/test/Test.scala
+++ b/src/main/scala/org/perl8/test/Test.scala
@@ -1,6 +1,8 @@
 package org.perl8.test
 
-/** Base trait for test classes in this framework
+/** Base trait for test classes in this framework. Any tests that should be
+  * autodiscovered by `sbt test` should extend this trait, and implement
+  * [[runTests]].
   */
 trait Test {
   /** Runs the test. The TAP stream will be written to Console.out and
@@ -9,6 +11,15 @@ trait Test {
   def run: Int =
     runTests(false)
 
+  /** Runs the test just like [[run]], but in a way that makes sense when test
+   *  results are being summarized rather than directly displayed.
+   *
+   *  Summarizing test reporters tend to repeatedly update the same line on
+   *  the terminal, so this method makes calls to
+   *  [[tap.TestBuilder#diag diag]] (which sends messages to stderr, where
+   *  they are typically displayed as-is) prefix the message with a newline,
+   *  to ensure that the output starts on its own line.
+   */
   def runInHarness: Int =
     runTests(true)