Add documentation

Author: nicolasstucki

compiler/src/dotty/tools/dotc/core/quoted/PickledQuotes.scala

@@ -22,7 +22,7 @@ import scala.reflect.ClassTag
 object PickledQuotes {
   import tpd._
 
-  /** Pickle the tree of the a quoted.Expr */
+  /** Pickle the tree of the quoted.Expr */
   def pickleExpr(tree: Tree)(implicit ctx: Context): scala.quoted.Expr[Any] = {
     // Check that there are no free variables
     new TreeTraverser {

library/src/scala/quoted/Expr.scala

@@ -5,7 +5,14 @@ import scala.runtime.quoted.Unpickler.Pickled
 
 sealed abstract class Expr[T] {
   final def unary_~ : T = throw new Error("~ should have been compiled away")
+
+  /** Evaluate the contents of this expression and return the result.
+   *
+   *  May throw a FreeVariableError on expressions that came from an inline macro.
+   */
   final def run(implicit toolbox: Toolbox[T]): T = toolbox.run(this)
+
+  /** Show a source code like representation of this expression */
   final def show(implicit toolbox: Toolbox[T]): String = toolbox.show(this)
 }
 
@@ -36,7 +43,13 @@ object Exprs {
     override def toString: String = s"Expr($value)"
   }
 
-  /** An Expr backed by a tree. Only the current compiler trees are allowed. */
+  /** An Expr backed by a tree. Only the current compiler trees are allowed.
+   *
+   *  These expressions are used for arguments of inline macros. They contain and actual tree
+   *  from the program that is being expanded by the macro.
+   *
+   *  May contain references to code defined outside this Expr instance.
+   */
   final class TreeExpr[Tree](val tree: Tree, pickle: => Expr[_]) extends quoted.Expr[Any] {
     def pickled[T]: Expr[T] = pickle.asInstanceOf[Expr[T]]
     override def toString: String = s"Expr(<raw>)"

library/src/scala/quoted/FreeVariableError.scala

@@ -1,3 +1,8 @@
 package scala.quoted
 
+/** Exception is thrown when trying to evaluate the contents of an expression
+ *  that has free variables (i.e. has some local references to code that is
+ *  outside of the expression). This can happen on Expr that passed as arguments to
+ *  an inline macro.
+ */
 class FreeVariableError(val name: String) extends QuoteError("Free variable " + name + " could not be handled")