Merge pull request #3579 from densh/topic/quasiquotes-scaladoc

Add ScalaDoc to Quasiquotes and Liftables parts of api

2 files changed, 58 insertions, 7 deletions

diff --git a/src/reflect/scala/reflect/api/Liftables.scala b/src/reflect/scala/reflect/api/Liftables.scala
index 6ac5557caa..ec9d85b69e 100644
--- a/src/reflect/scala/reflect/api/Liftables.scala
+++ b/src/reflect/scala/reflect/api/Liftables.scala
@@ -2,27 +2,72 @@ package scala
 package reflect
 package api
 
-// TODO: needs a Scaladoc
 trait Liftables { self: Universe =>
 
-  // TODO: needs a Scaladoc
+  /** A type class that defines a representation of `T` as a `Tree`.
+   *
+   *  @see [[http://docs.scala-lang.org/overviews/macros/quasiquotes.html#lifting]]
+   */
   trait Liftable[T] {
     def apply(value: T): Tree
   }
 
-  // TODO: needs a Scaladoc
+  /** Companion to `Liftable` type class that contains standard instances
+   *  and provides a helper `apply` method to simplify creation of new ones.
+   */
   object Liftable extends StandardLiftableInstances {
+    /** A helper method that simplifies creation of `Liftable` instances.
+     *  Takes a type and a function that maps that type to a tree representation.
+     *
+     *  For example to write Liftable for object one might use it like:
+     *
+     *  {{{
+     *  scala> object O
+     *
+     *  scala> val Oref = symbolOf[O.type].asClass.module
+     *
+     *  scala> implicit val liftO = Liftable[O.type] { _ => q"$Oref" }
+     *
+     *  scala> val lifted = q"$O"
+     *  lifted: universe.Tree = O
+     *  }}}
+     *
+     *  @see [[http://docs.scala-lang.org/overviews/macros/quasiquotes.html#lifting]]
+     */
     def apply[T](f: T => Tree): Liftable[T] =
       new Liftable[T] { def apply(value: T): Tree = f(value) }
   }
 
-  // TODO: needs a Scaladoc
+  /** A type class that defines a way to extract instance of `T` from a `Tree`.
+   *
+   *  @see [[http://docs.scala-lang.org/overviews/macros/quasiquotes.html#unlifting]]
+   */
   trait Unliftable[T] {
     def unapply(tree: Tree): Option[T]
   }
 
-  // TODO: needs a Scaladoc
+  /** Companion to `Unliftable` type class that contains standard instances
+   *  and provides a helper `apply` method to simplify creation of new ones.
+   */
   object Unliftable extends StandardUnliftableInstances {
+    /** A helper method that simplifies creation of `Unliftable` instances.
+     *  Takes a partial function which is defined on correct representations of `T`
+     *  and returns corresponing instances.
+     *
+     *  For example to extract a reference to an object as object itself:
+     *
+     *  {{{
+     *  scala> object O
+     *
+     *  scala> val Oref = symbolOf[O.type].asClass.module
+     *
+     *  scala> implicit val unliftO = Unliftable[O.type] { case t if t.symbol == Oref => O }
+     *
+     *  scala> val q"${_: O.type}" = q"$Oref"
+     *  }}}
+     *
+     *  @see [[http://docs.scala-lang.org/overviews/macros/quasiquotes.html#unlifting]]
+     */
     def apply[T](pf: PartialFunction[Tree, T]): Unliftable[T] = new Unliftable[T] {
       def unapply(value: Tree): Option[T] = pf.lift(value)
     }
diff --git a/src/reflect/scala/reflect/api/Quasiquotes.scala b/src/reflect/scala/reflect/api/Quasiquotes.scala
index c939eee164..0065926e3b 100644
--- a/src/reflect/scala/reflect/api/Quasiquotes.scala
+++ b/src/reflect/scala/reflect/api/Quasiquotes.scala
@@ -3,10 +3,16 @@ package api
 
 trait Quasiquotes { self: Universe =>
 
-  // implementation is hardwired to `dispatch` method of `scala.tools.reflect.quasiquotes.Quasiquotes`
-  // using the mechanism implemented in `scala.tools.reflect.FastTrack`
+  /** Implicit class that introduces `q`, `tq`, `cq,` `p` and `fq` string interpolators
+   *  that are also known as quasiquotes. With their help you can easily manipulate
+   *  Scala reflection ASTs.
+   *
+   *  @see [[http://docs.scala-lang.org/overviews/macros/quasiquotes.html]]
+   */
   implicit class Quasiquote(ctx: StringContext) {
     protected trait api {
+      // implementation is hardwired to `dispatch` method of `scala.tools.reflect.quasiquotes.Quasiquotes`
+      // using the mechanism implemented in `scala.tools.reflect.FastTrack`
       def apply[T](args: T*): Tree = macro ???
       def unapply(scrutinee: Any): Any = macro ???
     }