more documentation

13 files changed, 85 insertions, 6 deletions

diff --git a/src/main/scala/org/perl8/test/Test.scala b/src/main/scala/org/perl8/test/Test.scala
index 436719c..ffe75b9 100644
--- a/src/main/scala/org/perl8/test/Test.scala
+++ b/src/main/scala/org/perl8/test/Test.scala
@@ -7,6 +7,12 @@ package org.perl8.test
 trait Test {
   /** Runs the test. The TAP stream will be written to Console.out and
     * Console.err, so you can swap these out as required in order to parse it.
+    *
+    * @return The exit code that the test produced. Success is indicated by 0,
+    *         failure to run the correct number of tests by 255, and any other
+    *         failure by the number of tests that failed. This should be used
+    *         by reporters which run a single test, which can call
+    *         `sys.exit(exitCode)`
     */
   def run: Int =
     runTests(false)
@@ -16,9 +22,9 @@ trait Test {
    *
    *  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.
+   *  [[org.perl8.test.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)
diff --git a/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala b/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala
index b0548e4..8d50528 100644
--- a/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala
+++ b/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala
@@ -1,5 +1,16 @@
 package org.perl8.test.harness
 
+/** Classes that implement `MultiTestReporter` are capable of running a group
+  * of test classes, given their names. This typically involves some sort of
+  * summarization.
+  *
+  * See also: [[org.perl8.test.harness.MultiTestReporter]].
+  */
 trait MultiTestReporter {
+  /** Runs the test classes identifed by the list of fully qualified class
+    * names `testNames`.
+    *
+    * @return The exit code for the harness to use. Will be 0 on success.
+    */
   def run (testNames: Seq[String]): Int
 }
diff --git a/src/main/scala/org/perl8/test/harness/Reporter.scala b/src/main/scala/org/perl8/test/harness/Reporter.scala
index 536636f..749cb30 100644
--- a/src/main/scala/org/perl8/test/harness/Reporter.scala
+++ b/src/main/scala/org/perl8/test/harness/Reporter.scala
@@ -1,5 +1,15 @@
 package org.perl8.test.harness
 
+/** Classes that implement `Reporter` are capable of running a test class,
+  * given its name.
+  *
+  * See also: [[org.perl8.test.harness.MultiTestReporter]].
+  */
 trait Reporter {
+  /** Runs the test class identifed by the fully qualified class name
+    * `testName`.
+    *
+    * @return The exit code for the harness to use. Will be 0 on success.
+    */
   def run (testName: String): Int
 }
diff --git a/src/main/scala/org/perl8/test/harness/SummarizedTests.scala b/src/main/scala/org/perl8/test/harness/SummarizedTests.scala
index 3688011..207cc18 100644
--- a/src/main/scala/org/perl8/test/harness/SummarizedTests.scala
+++ b/src/main/scala/org/perl8/test/harness/SummarizedTests.scala
@@ -9,8 +9,18 @@ import scala.concurrent.Future
 import org.perl8.test.tap.{Parser,TAPEvent,TAPResult,TodoDirective}
 import org.perl8.test.Test
 
+/** This is a trait for classes that run tests and summarize the results. It
+  * provides a single `runOneTest` method, which runs a test class and
+  * produces a stream of [[org.perl8.test.tap.TAPEvent TAP events]] which can
+  * be used to produce whatever summarized output you need.
+  */
 trait SummarizedTests {
-  def runOneTest (test: Test, cb: TAPEvent => Unit): TAPResult = {
+  /** Runs a single [[org.perl8.test.Test test]] instance, calling `cb` with
+    * each [[org.perl8.test.tap.TAPEvent TAP event]] as it is produced.
+    *
+    * @return The overall result of the test instance.
+    */
+  protected def runOneTest (test: Test, cb: TAPEvent => Unit): TAPResult = {
     val out = new PipedOutputStream
     val in  = new PipedInputStream(out)
 
diff --git a/src/main/scala/org/perl8/test/harness/SummaryReporter.scala b/src/main/scala/org/perl8/test/harness/SummaryReporter.scala
index 083290b..1901bcf 100644
--- a/src/main/scala/org/perl8/test/harness/SummaryReporter.scala
+++ b/src/main/scala/org/perl8/test/harness/SummaryReporter.scala
@@ -4,6 +4,10 @@ import org.perl8.test.tap.{TAPEvent,StartEvent,ResultEvent,PlanEvent,EndEvent}
 import org.perl8.test.tap.{TAPResult,TodoDirective}
 import org.perl8.test.Test
 
+/** Runs a series of tests. The TAP output from these tests is parsed, and
+  * output is produced which is similar in style to Perl's
+  * [[https://metacpan.org/module/Test::Harness Test::Harness]].
+  */
 class SummaryReporter extends MultiTestReporter with SummarizedTests {
   def run (testNames: Seq[String]): Int = {
     val results = runTests(testNames)
@@ -12,7 +16,7 @@ class SummaryReporter extends MultiTestReporter with SummarizedTests {
     if (success) 0 else 1
   }
 
-  def runTests (testNames: Seq[String]): Map[String, TAPResult] = {
+  protected def runTests (testNames: Seq[String]): Map[String, TAPResult] = {
     val maxLength = testNames.map(_.length).max
 
     testNames.map { name =>
@@ -70,7 +74,7 @@ class SummaryReporter extends MultiTestReporter with SummarizedTests {
     }.toMap
   }
 
-  def printTestSummary (
+  protected def printTestSummary (
     success: Boolean,
     results: Map[String, TAPResult]
   ) {
diff --git a/src/main/scala/org/perl8/test/harness/TAPReporter.scala b/src/main/scala/org/perl8/test/harness/TAPReporter.scala
index 47a88c5..58dd175 100644
--- a/src/main/scala/org/perl8/test/harness/TAPReporter.scala
+++ b/src/main/scala/org/perl8/test/harness/TAPReporter.scala
@@ -3,6 +3,9 @@ package org.perl8.test.harness
 import org.perl8.test.tap
 import org.perl8.test.Test
 
+/** Runs a single test. The TAP stream from that test is written directly to
+  * stdout/stderr.
+  */
 class TAPReporter extends Reporter {
   def run (testName: String): Int =
     newInstance[Test](testName).run
diff --git a/src/main/scala/org/perl8/test/harness/package.scala b/src/main/scala/org/perl8/test/harness/package.scala
index a5641e8..fbebf07 100644
--- a/src/main/scala/org/perl8/test/harness/package.scala
+++ b/src/main/scala/org/perl8/test/harness/package.scala
@@ -1,14 +1,27 @@
 package org.perl8.test
 
+/** Classes to handle running test instances and providing output.
+  */
 package object harness {
   import scala.reflect.{ClassTag,classTag}
 
+  /** Loads `className`, returning the
+    * [[http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html java.lang.Class]]
+    * instance.
+    */
   def loadClass[T: ClassTag] (className: String): Class[_] =
     classTag[T].runtimeClass.getClassLoader.loadClass(className)
 
+  /** Loads `className` and creates a new instance of it, using the
+    * no-argument constructor.
+    */
   def newInstance[T: ClassTag] (className: String): T =
     loadClass[T](className).newInstance.asInstanceOf[T]
 
+  /** Loads `className` and creates a new instance of it, using a
+    * one-argument constructor. Passes `arg` as the argument to the
+    * constructor.
+    */
   def newInstance[T: ClassTag, U <: AnyRef: ClassTag] (
     className: String,
     arg: U
diff --git a/src/main/scala/org/perl8/test/sbt/Fingerprint.scala b/src/main/scala/org/perl8/test/sbt/Fingerprint.scala
index 9cea6f1..c60c97b 100644
--- a/src/main/scala/org/perl8/test/sbt/Fingerprint.scala
+++ b/src/main/scala/org/perl8/test/sbt/Fingerprint.scala
@@ -2,6 +2,9 @@ package org.perl8.test.sbt
 
 import org.scalatools.testing
 
+/** Implementation of
+  * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Fingerprint.java org.scalatools.testing.Fingerprint]].
+  */
 object Fingerprint extends testing.SubclassFingerprint {
   def isModule:       Boolean = false
   def superClassName: String  = "org.perl8.test.Test"
diff --git a/src/main/scala/org/perl8/test/sbt/Framework.scala b/src/main/scala/org/perl8/test/sbt/Framework.scala
index 74ea6d8..e8b5c57 100644
--- a/src/main/scala/org/perl8/test/sbt/Framework.scala
+++ b/src/main/scala/org/perl8/test/sbt/Framework.scala
@@ -2,6 +2,9 @@ package org.perl8.test.sbt
 
 import org.scalatools.testing
 
+/** Implementation of
+  * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Framework.java org.scalatools.testing.Framework]].
+  */
 class Framework extends testing.Framework {
   val name:  String                     = "Perl8 Test"
   val tests: Array[testing.Fingerprint] = Array(Fingerprint)
diff --git a/src/main/scala/org/perl8/test/sbt/Runner.scala b/src/main/scala/org/perl8/test/sbt/Runner.scala
index f403b32..442e4eb 100644
--- a/src/main/scala/org/perl8/test/sbt/Runner.scala
+++ b/src/main/scala/org/perl8/test/sbt/Runner.scala
@@ -5,6 +5,10 @@ import org.scalatools.testing
 import org.perl8.test.harness.SummaryReporter
 import org.perl8.test.Test
 
+/** Implementation of
+  * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Runner2.java org.scalatools.testing.Runner2]]
+  * using [[org.perl8.test.sbt.SBTReporter SBTReporter]].
+  */
 class Runner (
   loader:  ClassLoader,
   loggers: Array[testing.Logger]
diff --git a/src/main/scala/org/perl8/test/sbt/SBTReporter.scala b/src/main/scala/org/perl8/test/sbt/SBTReporter.scala
index 148c380..5277904 100644
--- a/src/main/scala/org/perl8/test/sbt/SBTReporter.scala
+++ b/src/main/scala/org/perl8/test/sbt/SBTReporter.scala
@@ -6,6 +6,8 @@ import org.perl8.test.harness.{Reporter,SummarizedTests}
 import org.perl8.test.tap.{TAPEvent,ResultEvent,EndEvent}
 import org.perl8.test.Test
 
+/** Runs a single test under the SBT test harness.
+  */
 class SBTReporter (
   loader:       ClassLoader,
   loggers:      Array[testing.Logger],
diff --git a/src/main/scala/org/perl8/test/sbt/package.scala b/src/main/scala/org/perl8/test/sbt/package.scala
new file mode 100644
index 0000000..ce3652a
--- /dev/null
+++ b/src/main/scala/org/perl8/test/sbt/package.scala
@@ -0,0 +1,5 @@
+package org.perl8.test
+
+/** Classes for interoperating with `sbt test`.
+  */
+package object sbt
diff --git a/src/main/scala/org/perl8/test/tap/package.scala b/src/main/scala/org/perl8/test/tap/package.scala
index ffc732c..434497d 100644
--- a/src/main/scala/org/perl8/test/tap/package.scala
+++ b/src/main/scala/org/perl8/test/tap/package.scala
@@ -1,5 +1,10 @@
 package org.perl8.test
 
+/** Classes for TAP generation and parsing.
+  */
 package object tap {
+  /** Exception representing an error during parsing. It is thrown when a TAP
+    * line isn't recognized.
+    */
   case class ParseException (message: String) extends RuntimeException(message)
 }