more docs

2 files changed, 92 insertions, 19 deletions

diff --git a/src/main/scala/org/perl8/test/tap/TAPEvent.scala b/src/main/scala/org/perl8/test/tap/TAPEvent.scala
index 184e7ab..0f9318b 100644
--- a/src/main/scala/org/perl8/test/tap/TAPEvent.scala
+++ b/src/main/scala/org/perl8/test/tap/TAPEvent.scala
@@ -2,11 +2,38 @@ package org.perl8.test.tap
 
 import org.perl8.test.Plan
 
+/** An event emitted while parsing a TAP stream. */
 sealed trait TAPEvent
+
+/** The start of a TAP stream. */
 case object StartEvent extends TAPEvent
-case class  EndEvent (result: TAPResult) extends TAPEvent
-case class  ResultEvent (result: TestResult) extends TAPEvent
-case class  PlanEvent (plan: Plan) extends TAPEvent
+
+/** The end of a TAP stream.
+  * @param result The [[org.perl8.test.tap.TAPResult TAPResult]] containing
+  *               information about all of the tests which just finished
+  *               running. This will be the same thing that is returned by the
+  *               call to [[org.perl8.test.tap.Parser Parser]]'s `parse`
+  *               method.
+  */
+case class  EndEvent private[tap] (result: TAPResult) extends TAPEvent
+
+/** An individual test result.
+  * @param result The [[org.perl8.test.tap.TestResult TestResult]] containing
+  *               information about the corresponding test.
+  */
+case class  ResultEvent private[tap] (result: TestResult) extends TAPEvent
+
+/** A test plan.
+ * @param plan The [[org.perl8.test.Plan Plan]] corresponding to the line that
+ *             was parsed.
+ */
+case class  PlanEvent private[tap] (plan: Plan) extends TAPEvent
+
+/** The start of a subtest (currently unused). */
 case object SubtestStartEvent extends TAPEvent
-case class  SubtestEndEvent (result: TestResult) extends TAPEvent
-case class  CommentEvent (text: String) extends TAPEvent
+
+/** The end of a subtest (currently unused). */
+case class  SubtestEndEvent private[tap] (result: TestResult) extends TAPEvent
+
+/** A comment (currently unused). */
+case class  CommentEvent private[tap] (text: String) extends TAPEvent
diff --git a/src/main/scala/org/perl8/test/tap/TAPResult.scala b/src/main/scala/org/perl8/test/tap/TAPResult.scala
index 21c7986..2a23122 100644
--- a/src/main/scala/org/perl8/test/tap/TAPResult.scala
+++ b/src/main/scala/org/perl8/test/tap/TAPResult.scala
@@ -2,37 +2,47 @@ package org.perl8.test.tap
 
 import org.perl8.test.{Plan,NumericPlan,SkipAll}
 
-sealed trait Directive {
-  val message: Option[String]
-}
-case class SkipDirective (message: Option[String]) extends Directive
-case class TodoDirective (message: Option[String]) extends Directive
-
-class TestResult (
-  val passed:      Boolean,
-  val number:      Int,
-  val description: String,
-  val directive:   Option[Directive],
-  val subtest:     Option[TAPResult]
-)
-
+/** The summarized results of a TAP stream. Contains the
+  * [[org.perl8.test.Plan Plan]] that was given, as well as a list of
+  * [[org.perl8.test.tap.TestResult TestResults]] corresponding to each of the
+  * tests in the stream.
+  *
+  * @param plan    The [[org.perl8.test.Plan Plan]] from the TAP stream
+  * @param results The list of [[org.perl8.test.tap.TestResult TestResults]]
+  *                from the TAP stream
+  */
 class TAPResult (val plan: Plan, val results: Seq[TestResult]) {
+  /** Returns true if the number of tests executed was compatible with the
+    * provided test plan.
+    */
   val matchesPlan = plan match {
     case NumericPlan(n) => results.length == n
     case _              => results.length == 0
   }
 
+  /** Returns the number of test failures in the TAP stream. */
   val fails = results.count { r =>
     !r.passed && !r.directive.isDefined
   }
 
+  /** Returns true if all of the tests passed. */
   val testsPassed = fails == 0
 
+  /** Returns true if the TAP stream overall passed.
+    *
+    * Differs from `testsPassed` in that it also takes into account things
+    * like invalid plans.
+    */
   val success = plan match {
     case SkipAll(_) => true
     case _          => results.length > 0 && fails == 0 && matchesPlan
   }
 
+  /** Returns the exit code to use if running this test on its own.
+    *
+    * Success is indicated by 0, invalid TAP streams (such as incorrect plans)
+    * by 255, and other kinds of failures by the failure count.
+    */
   val exitCode =
     if (success) {
       0
@@ -44,3 +54,39 @@ class TAPResult (val plan: Plan, val results: Seq[TestResult]) {
       fails
     }
 }
+
+/** The result of a single test.
+  *
+  * @param passed      True if the test passed
+  * @param number      The test number in the TAP stream
+  * @param description The test description
+  * @param directive   The [[org.perl8.test.tap.Directive Directive]] (either
+  *                    skip or todo) that was provided for this test, if any
+  * @param subtest     The [[org.perl8.test.tap.TAPResult]] for the subtest
+  *                    that this test corresponds to, if any
+  */
+class TestResult (
+  val passed:      Boolean,
+  val number:      Int,
+  val description: String,
+  val directive:   Option[Directive],
+  val subtest:     Option[TAPResult]
+)
+
+/** A modifier associated with a test result. This is indicated by a `#` at
+  * the end of the result line, followed by the type of directive, and an
+  * optional message.
+  */
+sealed trait Directive {
+  val message: Option[String]
+}
+
+/** A directive indicating that this test was skipped. */
+case class SkipDirective private[tap] (
+  message: Option[String]
+) extends Directive
+
+/** A directive indicating that this test is known to fail. */
+case class TodoDirective private[tap] (
+  message: Option[String]
+) extends Directive