brief API documentation on some core settings types

main/Reference.scala

@@ -8,18 +8,30 @@ package sbt
 
 // in all of these, the URI must be resolved and normalized before it is definitive
 
+/** Identifies a project or build. */
 sealed trait Reference
+
+/** A fully resolved, unique identifier for a project or build. */
 sealed trait ResolvedReference extends Reference
 
+/** Identifies a build. */
 sealed trait BuildReference extends Reference
+/** Identifies the build for the current context. */
 final case object ThisBuild extends BuildReference
+/** Uniquely identifies a build by a URI. */
 final case class BuildRef(build: URI) extends BuildReference with ResolvedReference
 
+/** Identifies a project. */
 sealed trait ProjectReference extends Reference
+/** Uniquely references a project by a URI and a project identifier String. */
 final case class ProjectRef(build: URI, project: String) extends ProjectReference with ResolvedReference
+/** Identifies a project in the current build context. */
 final case class LocalProject(project: String) extends ProjectReference
+/** Identifies the root project in the specified build. */
 final case class RootProject(build: URI) extends ProjectReference
+/** Identifies the root project in the current build context. */
 final case object LocalRootProject extends ProjectReference
+/** Identifies the project for the current context. */
 final case object ThisProject extends ProjectReference
 
 object ProjectRef
@@ -33,6 +45,7 @@ object RootProject
 }
 object Reference
 {
+	/** Extracts the build URI from a Reference if one has been explicitly defined.*/
 	def uri(ref: Reference): Option[URI] = ref match {
 		case RootProject(b) => Some(b)
 		case ProjectRef(b, _) => Some(b)

main/Structure.scala

@@ -14,6 +14,7 @@ package sbt
 	import java.net.URI
 	import Path._
 
+/** Parses input and produces a task to run.  Constructed using the companion object. */
 sealed trait InputTask[T] {
 	def mapTask[S](f: Task[T] => Task[S]): InputTask[S]
 }
@@ -71,7 +72,14 @@ object InputTask
 }
 
 sealed trait Scoped { def scope: Scope; val key: AttributeKey[_] }
+
+/** A common type for SettingKey and TaskKey so that both can be used as inputs to tasks.*/
 sealed trait ScopedTaskable[T] extends Scoped
+
+/** Identifies a setting.  It consists of three parts: the scope, the name, and the type of a value associated with this key.
+* The scope is represented by a value of type Scope.
+* The name and the type are represented by a value of type AttributeKey[T].
+* Instances are constructed using the companion object. */
 sealed trait SettingKey[T] extends ScopedTaskable[T] with KeyedInitialize[T] with Scoped.ScopingSetting[SettingKey[T]] with Scoped.DefinableSetting[T] with Scoped.ListSetting[T, Id]
 {
 	val key: AttributeKey[T]
@@ -80,6 +88,11 @@ sealed trait SettingKey[T] extends ScopedTaskable[T] with KeyedInitialize[T] wit
 
 	protected[this] def make[S](other: Initialize[S])(f: (T, S) => T): Setting[T] = this <<= (this, other)(f)
 }
+
+/** Identifies a task.  It consists of three parts: the scope, the name, and the type of the value computed by a task associated with this key.
+* The scope is represented by a value of type Scope.
+* The name and the type are represented by a value of type AttributeKey[Task[T]].
+* Instances are constructed using the companion object. */
 sealed trait TaskKey[T] extends ScopedTaskable[T] with KeyedInitialize[Task[T]] with Scoped.ScopingSetting[TaskKey[T]] with Scoped.ListSetting[T, Task] with Scoped.DefinableTask[T]
 {
 	val key: AttributeKey[Task[T]]
@@ -88,6 +101,12 @@ sealed trait TaskKey[T] extends ScopedTaskable[T] with KeyedInitialize[Task[T]]
 
 	protected[this] def make[S](other: Initialize[Task[S]])(f: (T, S) => T): Setting[Task[T]] = this <<= (this, other) { (a,b) => (a,b) map f }
 }
+
+/** Identifies an input task.  An input task parses input and produces a task to run.
+* It consists of three parts: the scope, the name, and the type of the value produced by an input task associated with this key.
+* The scope is represented by a value of type Scope.
+* The name and the type are represented by a value of type AttributeKey[InputTask[T]]. */
+* Instances are constructed using the companion object. */
 sealed trait InputKey[T] extends Scoped with KeyedInitialize[InputTask[T]] with Scoped.ScopingSetting[InputKey[T]] with Scoped.DefinableSetting[InputTask[T]]
 {
 	val key: AttributeKey[InputTask[T]]
@@ -95,6 +114,7 @@ sealed trait InputKey[T] extends Scoped with KeyedInitialize[InputTask[T]] with
 	def in(scope: Scope): InputKey[T] = Scoped.scopedInput(Scope.replaceThis(this.scope)(scope), this.key)
 }
 
+/** Methods and types related to constructing settings, including keys, scopes, and initializations. */
 object Scoped
 {
 	implicit def taskScopedToKey[T](s: TaskKey[T]): ScopedKey[Task[T]] = ScopedKey(s.scope, s.key)
@@ -474,6 +494,7 @@ object Scoped
 
 	import Scoped.extendScoped
 
+/** Constructs InputKeys, which are associated with input tasks to define a setting.*/
 object InputKey
 {
 	def apply[T: Manifest](label: String, description: String = ""): InputKey[T] =
@@ -485,6 +506,8 @@ object InputKey
 	def apply[T](akey: AttributeKey[InputTask[T]]): InputKey[T] =
 		new InputKey[T] { val key = akey; def scope = Scope.ThisScope }
 }
+
+/** Constructs TaskKeys, which are associated with tasks to define a setting.*/
 object TaskKey
 {
 	def apply[T: Manifest](label: String, description: String = ""): TaskKey[T] =
@@ -498,6 +521,8 @@ object TaskKey
 
 	def local[T: Manifest]: TaskKey[T] = apply[T](AttributeKey.local[Task[T]])
 }
+
+/** Constructs SettingKeys, which are associated with a value to define a basic setting.*/
 object SettingKey
 {
 	def apply[T: Manifest](label: String, description: String = ""): SettingKey[T] =

util/collection/HList.scala

@@ -5,6 +5,8 @@ package sbt
 
 import Types._
 
+/** A minimal heterogeneous list type.  For background, see
+* http://apocalisp.wordpress.com/2010/07/06/type-level-programming-in-scala-part-6a-heterogeneous-list basics/ */
 sealed trait HList
 {
 	type Wrap[M[_]] <: HList

util/collection/KList.scala

@@ -8,7 +8,11 @@ import Types._
 /** A higher-order heterogeneous list.  It has a type constructor M[_] and
 * type parameters HL.  The underlying data is M applied to each type parameter.
 * Explicitly tracking M[_] allows performing natural transformations or ensuring
-* all data conforms to some common type. */
+* all data conforms to some common type.
+*
+* For background, see
+* http://apocalisp.wordpress.com/2010/11/01/type-level-programming-in-scala-part-8a-klist%C2%A0motivation/
+ */
 sealed trait KList[+M[_], HL <: HList]
 {
 	type Raw = HL