diff --git a/tasks/Incomplete.scala b/tasks/Incomplete.scala index e8bd1b5d3..cb9e9ca08 100644 --- a/tasks/Incomplete.scala +++ b/tasks/Incomplete.scala @@ -4,6 +4,14 @@ package sbt import Incomplete.{Error, Value => IValue} + +/** Describes why a task did not complete. +* +* @param node the task that did not complete that is described by this Incomplete instance +* @param tpe whether the task was incomplete because of an error or because it was skipped. Only Error is actually used and Skipped may be removed in the future. +* @param message an optional error message describing this incompletion +* @param causes a list of incompletions that prevented `node` from completing +* @param directCause the exception that caused `node` to not complete */ final case class Incomplete(node: Option[AnyRef], tpe: IValue = Error, message: Option[String] = None, causes: Seq[Incomplete] = Nil, directCause: Option[Throwable] = None) extends Exception(message.orNull, directCause.orNull) { override def toString = "Incomplete(node=" + node + ", tpe=" + tpe + ", msg=" + message + ", causes=" + causes + ", directCause=" + directCause +")" diff --git a/tasks/Node.scala b/tasks/Node.scala index c26faf5a7..ff4484b10 100644 --- a/tasks/Node.scala +++ b/tasks/Node.scala @@ -5,6 +5,11 @@ package sbt import Types._ +/** Represents a task node in a format understood by the task evaluation engine Execute. +* Heterogenous inputs (Mixed, tuple) and homogoneous (Uniform, sequence) and defined and consumed separately. +* +* @tparam A the task type +* @tparam T the type computed by this node */ trait Node[A[_], T] { type Mixed <: HList @@ -13,5 +18,6 @@ trait Node[A[_], T] val mixedIn: KList[A, Mixed] val uniformIn: Seq[A[Uniform]] + /** Computes the result of this task given the results from the inputs. */ def work(mixed: KList[Result, Mixed], uniform: Seq[Result[Uniform]]): Either[A[T], T] } diff --git a/tasks/standard/Action.scala b/tasks/standard/Action.scala index c80b1de03..f0dd91253 100644 --- a/tasks/standard/Action.scala +++ b/tasks/standard/Action.scala @@ -9,11 +9,18 @@ package sbt // Action, Task, and Info are intentionally invariant in their type parameter. // Various natural transformations used, such as PMap, require invariant type constructors for correctness +/** Defines a task compuation*/ sealed trait Action[T] +/** A direct computation of a value. */ final case class Pure[T](f: () => T) extends Action[T] +/** Applies a function to the result of evaluating a heterogeneous list of other tasks.*/ final case class Mapped[T, In <: HList](in: Tasks[In], f: Results[In] => T) extends Action[T] +/** Computes another task to evaluate based on results from evaluating other tasks.*/ final case class FlatMapped[T, In <: HList](in: Tasks[In], f: Results[In] => Task[T]) extends Action[T] +/** A computation `in` that requires other tasks `deps` to be evaluated first.*/ final case class DependsOn[T](in: Task[T], deps: Seq[Task[_]]) extends Action[T] +/** A computation that operates on the results of a homogeneous list of other tasks. +* It can either return another task to be evaluated or the final value.*/ final case class Join[T, U](in: Seq[Task[U]], f: Seq[Result[U]] => Either[Task[T], T]) extends Action[T] object Task @@ -22,11 +29,15 @@ object Task type Results[HL <: HList] = KList[Result, HL] } +/** Combines metadata `info` and a computation `work` to define a task. */ final case class Task[T](info: Info[T], work: Action[T]) { override def toString = info.name getOrElse ("Task(" + info + ")") override def hashCode = info.hashCode } +/** Used to provide information about a task, such as the name, description, and tags for controlling concurrent execution. +* @param attributes Arbitrary user-defined key/value pairs describing this task +* @param post a transformation that takes the result of evaluating this task and produces user-defined key/value pairs. */ final case class Info[T](attributes: AttributeMap = AttributeMap.empty, post: T => AttributeMap = const(AttributeMap.empty)) { import Info._