Add comments

2 files changed, 23 insertions, 8 deletions

diff --git a/core/src/main/scala/mill/discover/Discovered.scala b/core/src/main/scala/mill/discover/Discovered.scala
index f6b6a6c3..e0232c1a 100644
--- a/core/src/main/scala/mill/discover/Discovered.scala
+++ b/core/src/main/scala/mill/discover/Discovered.scala
@@ -8,7 +8,9 @@ import mill.discover.Router.{EntryPoint, Result}
 import scala.language.experimental.macros
 import scala.reflect.macros.blackbox.Context
 
-
+/**
+  * Allows you to implicitly summon up a build [[Mirror]] for arbitrary types
+  */
 class Discovered[T](val mirror: Mirror[T, T]){
 
   def targets(obj: T) = Mirror.traverse(mirror) { (h, p) =>
diff --git a/core/src/main/scala/mill/discover/Mirror.scala b/core/src/main/scala/mill/discover/Mirror.scala
index 3cfc0962..8456d976 100644
--- a/core/src/main/scala/mill/discover/Mirror.scala
+++ b/core/src/main/scala/mill/discover/Mirror.scala
@@ -1,11 +1,18 @@
 package mill.discover
 
-import mill.define.Task
+import mill.define.{Target, Task}
 import mill.discover.Router.EntryPoint
 
 import scala.language.experimental.macros
 
-
+/**
+  * Metadata about a build that is extracted & materialized at compile-time,
+  * letting us use it at run-time without needing to use the heavy weight
+  * scala-reflect library.
+  *
+  * Note that [[Mirror]] allows you to store and inspect metadata of a type
+  * [[T]] even without a concrete instance of [[T]] itself.
+  */
 case class Mirror[-T, V](node: T => V,
                          commands: Seq[EntryPoint[V]],
                          targets: Seq[Mirror.TargetPoint[V, _]],
@@ -25,18 +32,24 @@ object Mirror{
     rec(Nil, hierarchy)
   }
 
-
-  case class LabelledTarget[T](target: Task[T],
-                               format: upickle.default.ReadWriter[T],
+  /**
+    * A target after being materialized in a concrete build
+    */
+  case class LabelledTarget[V](target: Task[V],
+                               format: upickle.default.ReadWriter[V],
                                segments: Seq[String])
 
+  /**
+    * Represents metadata about a particular target, before the target is
+    * materialized for a concrete build
+    */
   case class TargetPoint[T, V](label: String,
                                format: upickle.default.ReadWriter[V],
-                               run: T => Task[V]) {
+                               run: T => Target[V]) {
     def labelled(t: T, segments: Seq[String]) = LabelledTarget(run(t), format, segments :+ label)
   }
 
-  def makeTargetPoint[T, V](label: String, func: T => Task[V])
+  def makeTargetPoint[T, V](label: String, func: T => Target[V])
                 (implicit f: upickle.default.ReadWriter[V]) = {
     TargetPoint(label, f, func)
   }