From c6453d42ea988dcea657c91a789f4f129152de22 Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Fri, 1 Mar 2013 17:17:58 -0600
Subject: docs for Consumer

---
 src/main/scala/org/perl8/test/tap/Consumer.scala | 38 +++++++++++++++++++--
 src/main/scala/org/perl8/test/tap/Producer.scala | 43 ++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 3 deletions(-)

diff --git a/src/main/scala/org/perl8/test/tap/Consumer.scala b/src/main/scala/org/perl8/test/tap/Consumer.scala
index 8c55e17..e822212 100644
--- a/src/main/scala/org/perl8/test/tap/Consumer.scala
+++ b/src/main/scala/org/perl8/test/tap/Consumer.scala
@@ -2,7 +2,13 @@ package org.perl8.test.tap
 
 import org.perl8.test.{Plan,NumericPlan,SkipAll}
 
+/** Contains a method to parse an individual line of TAP. */
 object Consumer {
+  /** Parses a line of TAP.
+    *
+    * @return A [[org.perl8.test.tap.Consumer.Line Line]] object corresponding
+    *         to the parsed line.
+    */
   def parseLine (line: String): Line = {
     commentRx.findFirstMatchIn(line).map { m =>
       m.subgroups match {
@@ -50,19 +56,37 @@ object Consumer {
     }
   }
 
+  /** The representation of a parsed line of TAP. */
   sealed trait Line {
+    /** The meaningful portion of the TAP line. */
     def contents: String
+    /** The indentation of the TAP line (used in subtests). */
     def indent:   String
 
+    /** The line itself that was parsed. */
     override def toString: String =
       indent + contents
   }
 
-  case class CommentLine (text: String, indent: String) extends Line {
+  /** A parsed TAP line containing a comment.
+    *
+    * @param text The text of the comment (not including the `#`).
+    */
+  case class CommentLine private[Consumer] (
+    text:   String,
+    indent: String
+  ) extends Line {
     def contents = "# " + text
   }
 
-  case class PlanLine (plan: Plan, indent: String) extends Line {
+  /** A parsed TAP line containing a test plan.
+    *
+    * @param plan The [[org.perl8.test.Plan Plan]] that this line represents.
+    */
+  case class PlanLine private[Consumer] (
+    plan:   Plan,
+    indent: String
+  ) extends Line {
     def contents = {
       val count = plan.plan
       val comment = plan match {
@@ -73,7 +97,15 @@ object Consumer {
     }
   }
 
-  case class ResultLine (result: TestResult, indent: String) extends Line {
+  /** A parsed TAP line containing a test result.
+    *
+    * @param result The [[org.perl8.test.tap.TestResult TestResult]] that this
+    *               line represents.
+    */
+  case class ResultLine private[Consumer] (
+    result: TestResult,
+    indent: String
+  ) extends Line {
     def contents = {
       val success = (if (result.passed) "ok" else "not ok") + " "
       val number = result.number + " "
diff --git a/src/main/scala/org/perl8/test/tap/Producer.scala b/src/main/scala/org/perl8/test/tap/Producer.scala
index ae42fdc..21997ad 100644
--- a/src/main/scala/org/perl8/test/tap/Producer.scala
+++ b/src/main/scala/org/perl8/test/tap/Producer.scala
@@ -1,35 +1,78 @@
 package org.perl8.test.tap
 
+/** Contains functions for producing individual lines of TAP.
+  */
 object Producer {
   import org.perl8.test.Plan
 
+  /** Returns a test result.
+    *
+    * @example `ok 4`
+    */
   def result (cond: Boolean, num: Int): String =
     (if (cond) "ok " else "not ok ") + num
 
+  /** Returns a test result that contains a description.
+    *
+    * @example `ok 28 - our test succeeded`
+    */
   def result (cond: Boolean, num: Int, desc: String): String =
     result(cond, num) + " " + desc
 
+  /** Returns a todo test result.
+    *
+    * @example `not ok 1 # TODO this doesn't work yet`
+    */
   def todoResult (cond: Boolean, num: Int, todo: String): String =
     result(cond, num) + " # TODO " + todo
 
+  /** Returns a todo test result that contains a description.
+    *
+    * @example `not ok 18 - test the feature # TODO can't figure this out`
+    */
   def todoResult (cond: Boolean, num: Int, desc: String, todo: String): String =
     result(cond, num, desc) + " # TODO " + todo
 
+  /** Returns a skipped test result.
+    *
+    * @example `ok 4 # skip`
+    */
   def skip (num: Int): String =
     "ok " + num + " # skip"
 
+  /** Returns a skipped test result with a reason.
+    *
+    * @example `ok 4 # skip this test won't run here`
+    */
   def skip (num: Int, reason: String): String =
     skip(num) + " " + reason
 
+  /** Returns a comment.
+    *
+    * @example `# this is a comment`
+    */
   def comment (message: String): String =
     message.split("\n").map(m => "# " + m).mkString("\n")
 
+  /** Returns a test plan.
+    *
+    * @example `1..5` ([[org.perl8.test.NumericPlan NumericPlan]])
+    * @example `1..0 # SKIP don't run this test` ([[org.perl8.test.SkipAll SkipAll]])
+    */
   def plan (plan: Plan): String =
     plan.skipAll.map(m => "1..0 # SKIP " + m).getOrElse("1.." + plan.plan)
 
+  /** Returns a bail out.
+    *
+    * @example `Bail out!`
+    */
   def bailOut: String =
     "Bail out!"
 
+  /** Returns a bail out with a reason.
+    *
+    * @example `Bail out!  Not supported on this platform.`
+    */
   def bailOut (message: String): String =
     "Bail out!  " + message
 }
-- 
cgit v1.2.3