Add some doccomments

3 files changed, 26 insertions, 0 deletions

diff --git a/core/src/main/scala/mill/define/Cross.scala b/core/src/main/scala/mill/define/Cross.scala
index 2dd4d2fe..e7d0d843 100644
--- a/core/src/main/scala/mill/define/Cross.scala
+++ b/core/src/main/scala/mill/define/Cross.scala
@@ -32,6 +32,16 @@ object Cross{
   }
 }
 
+/**
+  * Models "cross-builds": sets of duplicate builds which differ only in the
+  * value of one or more "case" variables whose values are determined at runtime.
+  * Used via:
+  *
+  * object foo extends Cross[FooModule]("bar", "baz", "qux")
+  * class FooModule(v: String) extends Module{
+  *   ...
+  * }
+  */
 class Cross[T](cases: Any*)
                (implicit ci: Cross.Factory[T],
                 val ctx: Module.Ctx){
diff --git a/core/src/main/scala/mill/define/Module.scala b/core/src/main/scala/mill/define/Module.scala
index db1d511a..c9240fa0 100644
--- a/core/src/main/scala/mill/define/Module.scala
+++ b/core/src/main/scala/mill/define/Module.scala
@@ -12,6 +12,15 @@ object Segment{
 }
 
 case class BasePath(value: Path)
+
+/**
+  * Models a path with the Mill build hierarchy, e.g.
+  *
+  * amm.util[2.11].test.compile
+  *
+  * .-separated segments are [[Segment.Label]]s, while []-delimited
+  * segments are [[Segment.Cross]]s
+  */
 case class Segments(value: Segment*){
   def ++(other: Seq[Segment]): Segments = Segments(value ++ other:_*)
   def ++(other: Segments): Segments = Segments(value ++ other.value:_*)
diff --git a/core/src/main/scala/mill/define/Task.scala b/core/src/main/scala/mill/define/Task.scala
index aa4d838a..eac64cd5 100644
--- a/core/src/main/scala/mill/define/Task.scala
+++ b/core/src/main/scala/mill/define/Task.scala
@@ -8,6 +8,13 @@ import upickle.default.{ReadWriter => RW, Reader => R, Writer => W}
 import scala.language.experimental.macros
 import scala.reflect.macros.blackbox.Context
 
+/**
+  * Models a single node in the Mill build graph, with a list of inputs and a
+  * single output of type [[T]].
+  *
+  * Generally not instantiated manually, but instead constructed via the
+  * [[Target.apply]] & similar macros.
+  */
 abstract class Task[+T] extends Task.Ops[T] with Applyable[Task, T]{
   /**
     * What other Targets does this Target depend on?