Added some docs to result type

1 files changed, 35 insertions, 9 deletions

diff --git a/main/api/src/mill/api/Result.scala b/main/api/src/mill/api/Result.scala
index b4071a99..c1aa5c5c 100644
--- a/main/api/src/mill/api/Result.scala
+++ b/main/api/src/mill/api/Result.scala
@@ -1,34 +1,60 @@
 package mill.api
 
-sealed trait Result[+T]{
+/**
+ * The result of a task execution.
+ * @tparam T The result type of the computed task.
+ */
+sealed trait Result[+T] {
   def map[V](f: T => V): Result[V]
   def asSuccess: Option[Result.Success[T]] = None
 }
-object Result{
+
+object Result {
   implicit def create[T](t: => T): Result[T] = {
     try Success(t)
     catch { case e: Throwable => Exception(e, new OuterStack(new java.lang.Exception().getStackTrace)) }
   }
-  case class Success[+T](value: T) extends Result[T]{
+
+  /**
+   * A successful task execution.
+   * @param value The value computed by the task.
+   * @tparam T The result type of the computed task.
+   */
+  case class Success[+T](value: T) extends Result[T] {
     def map[V](f: T => V) = Result.Success(f(value))
     override def asSuccess = Some(this)
   }
-  case object Skipped extends Result[Nothing]{
+
+  /**
+   * A task execution was skipped because of failures in it's dependencies.
+   */
+  case object Skipped extends Result[Nothing] {
     def map[V](f: Nothing => V) = this
   }
-  sealed trait Failing[+T] extends Result[T]{
+
+  /**
+   * A failed task execution.
+   * @tparam T The result type of the computed task.
+   */
+  sealed trait Failing[+T] extends Result[T] {
     def map[V](f: T => V): Failing[V]
   }
-  case class Failure[T](msg: String, value: Option[T] = None) extends Failing[T]{
+  case class Failure[T](msg: String, value: Option[T] = None) extends Failing[T] {
     def map[V](f: T => V) = Result.Failure(msg, value.map(f(_)))
   }
-  case class Exception(throwable: Throwable, outerStack: OuterStack) extends Failing[Nothing]{
+
+  /**
+   * A failed task which failed with a concrete exception.
+   * @param throwable The exception that describes or caused the failure.
+   * @param outerStack The [[OuterStack]] of the failed task.
+   */
+  case class Exception(throwable: Throwable, outerStack: OuterStack) extends Failing[Nothing] {
     def map[V](f: Nothing => V) = this
   }
-  class OuterStack(val value: Seq[StackTraceElement]){
+  class OuterStack(val value: Seq[StackTraceElement]) {
     override def hashCode() = value.hashCode()
 
-    override def equals(obj: scala.Any) = obj match{
+    override def equals(obj: scala.Any) = obj match {
       case o: OuterStack => value.equals(o.value)
       case _ => false
     }