Add docs

Author: nicolasstucki

compiler/src/dotty/tools/dotc/core/StagingContext.scala

@@ -11,7 +11,10 @@ object StagingContext {
   /** A key to be used in a context property that tracks the quoteation level */
   private val QuotationLevel = new Property.Key[Int]
 
-  private val QuotationContexts = new Property.Key[List[tpd.Tree]]
+  /** A key to be used in a context property that tracks the quoteation stack.
+   *  Stack containing the QuoteContext references recieved by the surrounding quotes.
+   */
+  private val QuoteQontextStack = new Property.Key[List[tpd.Tree]]
 
   /** All enclosing calls that are currently inlined, from innermost to outermost. */
   def level(implicit ctx: Context): Int =
@@ -21,25 +24,27 @@ object StagingContext {
   def quoteContext(implicit ctx: Context): Context =
     ctx.fresh.setProperty(QuotationLevel, level + 1)
 
-  /** Context with an incremented quotation level. */
+  /** Context with an incremented quotation level and pushes a refecence to a QuoteContext on the quote context stack */
   def pushQuoteContext(qctxRef: tpd.Tree)(implicit ctx: Context): Context =
-    val old = ctx.property(QuotationContexts).getOrElse(List.empty)
+    val old = ctx.property(QuoteQontextStack).getOrElse(List.empty)
     ctx.fresh.setProperty(QuotationLevel, level + 1)
-             .setProperty(QuotationContexts, qctxRef :: old)
+             .setProperty(QuoteQontextStack, qctxRef :: old)
 
   /** Context with a decremented quotation level. */
   def spliceContext(implicit ctx: Context): Context =
     ctx.fresh.setProperty(QuotationLevel, level - 1)
 
+  /** Context with a decremented quotation level and pops the Some of top of the quote context stack or None if the stack is empty.
+   *  The quotation stack could be empty if we are in a top level splice or an eroneous splice directly witin a top level splice.
+   */
   def popQuoteContext()(implicit ctx: Context): (Option[tpd.Tree], Context) =
     val ctx1 = ctx.fresh.setProperty(QuotationLevel, level - 1)
     val head =
-      ctx.property(QuotationContexts) match
+      ctx.property(QuoteQontextStack) match
         case Some(x :: xs) =>
-          ctx1.setProperty(QuotationContexts, xs)
+          ctx1.setProperty(QuoteQontextStack, xs)
           Some(x)
         case _ =>
           None // Splice at level 0 or lower
     (head, ctx1)
 }
-

library/src/scala/quoted/QuoteContext.scala

@@ -12,14 +12,30 @@ import scala.quoted.show.SyntaxHighlight
  */
 class QuoteContext(val tasty: scala.tasty.Reflection) { self =>
 
-  // TODO
-  type NestedContext = QuoteContext { val tasty: self.tasty.type }
+  /** Type of a QuoteContext profided by a splice within a quote that took this context.
+   *  It is only required if working with the reflection API.
+   *
+   *  Usually it is infered by the quotes an splices typing. But sometimes it is necessary
+   *  to explicitly state that a context is nested as in the following example:
+   *
+   *  ```scala
+   *  def run(using qctx: QuoteContext)(tree: qctx.tasty.Tree): Unit =
+   *    def nested()(using qctx.NestedContext): Expr[Int] = '{  ${ makeExpr(tree) } + 1  }
+   *    '{  ${ nested() } + 2 }
+   *  def makeExpr(using qctx: QuoteContext)(tree: qctx.tasty.Tree): Expr[Int] = ???
+   *  ```
+   */
+  type NestedContext = QuoteContext {
+    val tasty: self.tasty.type
+  }
 
+  /** Show the fully elaborated source code representation of an expression */
   def show(expr: Expr[_], syntaxHighlight: SyntaxHighlight): String = {
     import tasty.{_, given}
     expr.unseal.showWith(syntaxHighlight)
   }
 
+  /** Show the fully elaborated source code representation of a type */
   def show(tpe: Type[_], syntaxHighlight: SyntaxHighlight): String = {
     import tasty.{_, given}
     tpe.unseal.showWith(syntaxHighlight)

tests/pos/i8045b.scala

@@ -0,0 +1,8 @@
+import scala.quoted._
+object Test
+  def run(using qctx: QuoteContext)(tree: qctx.tasty.Tree): Unit =
+    def nested()(using qctx.NestedContext): Expr[Int] =
+      '{  ${ makeExpr(tree) } + 1  }
+    '{  ${ nested() } + 2 }
+
+  def makeExpr(using qctx: QuoteContext)(tree: qctx.tasty.Tree): Expr[Int] = ???