API documentation

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 +")"

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]
 }

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._