fix uncompiling snippets and incorrect indentation for reflection snippet docs

Author: rochala

library/src/scala/Tuple.scala

@@ -156,11 +156,11 @@ object Tuple {
   /** Filters out those members of the tuple for which the predicate `P` returns `false`.
    *  A predicate `P[X]` is a type that can be either `true` or `false`. For example:
    *  ```scala
-   *  type IsString[x] = x match {
+   *  type IsString[x] <: Boolean = x match {
    *    case String => true
    *    case _ => false
    *  }
-   *  Filter[(1, "foo", 2, "bar"), IsString] =:= ("foo", "bar")
+   *  summon[Tuple.Filter[(1, "foo", 2, "bar"), IsString] =:= ("foo", "bar")]
    *  ```
    *  @syntax markdown
    */

library/src/scala/quoted/Exprs.scala

@@ -5,14 +5,11 @@ object Exprs:
   /** Matches literal sequence of literal constant value expressions and return a sequence of values.
    *
    *  Usage:
-   *  ```scala sc:nocompile
+   *  ```scala sc:macrocompile
    *  inline def sum(args: Int*): Int = ${ sumExpr('args) }
    *  def sumExpr(argsExpr: Expr[Seq[Int]])(using Quotes): Expr[Int] = argsExpr match
-   *    case Varargs(Exprs(args)) =>
-   *    case Varargs(Exprs(args)) =>
+   *    case Varargs(Exprs(args)) => ???
    *      // args: Seq[Int]
-   *      ...
-   *  }
    *  ```
    *  To directly get the value of all expressions in a sequence `exprs: Seq[Expr[T]]` consider using `exprs.map(_.value)`/`exprs.map(_.valueOrError)` instead.
    */

library/src/scala/quoted/Quotes.scala

@@ -6,10 +6,11 @@ import scala.reflect.TypeTest
 /** Current Quotes in scope
  *
  *  Usage:
- *  ```scala sc:nocompile
+ *  ```scala
+ *  import scala.quoted._
  *  def myExpr[T](using Quotes): Expr[T] = {
  *     import quotes.reflect._
- *     ...
+ *     ???
  *  }
  *  ```
  */
@@ -2532,17 +2533,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
         /** Convert this `TypeRepr` to an `Type[?]`
         *
         *  Usage:
-        *  ```scala
-        *  //{
-        *  def f(using Quotes) = {
+        *  ```scala sc:usingquotes
         *  val typeRepr: TypeRepr = ???
-        *  //}
         *  typeRepr.asType match
         *    case '[t] =>
         *      '{ val x: t = ??? }
-        *  //{
-        *  }
-        *  //}
         *  ```
         */
         def asType: Type[?]

library/src/scala/quoted/Type.scala

@@ -26,20 +26,13 @@ object Type:
    *  Returns None if the type is not a singleton constant type.
    *
    *  Example usage:
-   *  ```scala
-   *  //{
+   *  ```scala sc:usingquotes
    *  import scala.deriving.*
-   *  def f(using Quotes) = {
    *  import quotes.reflect.*
    *  val expr: Expr[Any] = ???
-   *  //}
-   *  expr match {
+   *  expr match
    *    case '{ $mirrorExpr : Mirror.Sum { type MirroredLabel = label } } =>
    *      Type.valueOfConstant[label] // Option[String]
-   *  }
-   *  //{
-   *  }
-   *  //}
    *  ```
    */
   def valueOfConstant[T](using Type[T])(using Quotes): Option[T] =
@@ -50,20 +43,14 @@ object Type:
    *  Returns None if the type is not a tuple singleton constant types.
    *
    *  Example usage:
-   *  ```scala
+   *  ```scala sc:usingquotes
    *  //{
    *  import scala.deriving.*
-   *  def f(using Quotes) = {
    *  import quotes.reflect.*
    *  val expr: Expr[Any] = ???
-   *  //}
-   *  expr match {
+   *  expr match
    *    case '{ type label <: Tuple; $mirrorExpr : Mirror.Sum { type MirroredElemLabels = `label` } } =>
    *      Type.valueOfTuple[label] // Option[Tuple]
-   *  }
-   *  //{
-   *  }
-   *  //}
    *  ```
    */
   @since("3.1")

library/src/scala/quoted/Varargs.scala

@@ -16,15 +16,9 @@ object Varargs {
    *    `'{ Seq($e1, $e2, ...) }` typed as an `Expr[Seq[T]]`
    *
    *  Usage:
-   *  ```scala
-   *  //{
-   *  def f(using Quotes) = {
+   *  ```scala sc:usingquotes
    *  import quotes.reflect.*
-   *  //}
    *  '{ List(${Varargs(List('{1}, '{2}, '{3}))}: _*) } // equivalent to '{ List(1, 2, 3) }
-   *  //{
-   *  }
-   *  //}
    *  ```
    */
   def apply[T](xs: Seq[Expr[T]])(using Type[T])(using Quotes): Expr[Seq[T]] = {
@@ -35,19 +29,12 @@ object Varargs {
   /** Matches a literal sequence of expressions and return a sequence of expressions.
    *
    *  Usage:
-   *  ```scala sc:nocompile
-   *  //{
-   *  object O {
-   *  //}
+   *  ```scala sc:macrocompile
    *  inline def sum(args: Int*): Int = ${ sumExpr('args) }
    *  def sumExpr(argsExpr: Expr[Seq[Int]])(using Quotes): Expr[Int] = argsExpr match
-   *    case Varargs(argVarargs) =>
+   *    case Varargs(argVarargs) => ???
    *      // argVarargs: Seq[Expr[Int]]
-   *      ???
-   *  //{
-   *  }
-   *  //}
-   *  ```
+   *
    */
   def unapply[T](expr: Expr[Seq[T]])(using Quotes): Option[Seq[Expr[T]]] = {
     import quotes.reflect._

project/Build.scala

@@ -1845,8 +1845,7 @@ object ScaladocConfigs {
       .add(VersionsDictionaryUrl("https://scala-lang.org/api/versions.json"))
       .add(DocumentSyntheticTypes(true))
       .add(SnippetCompiler(List(
-        s"${dottyLibRoot}/scala/quoted=compile",
-        s"${dottyLibRoot}/scala/compiletime=compile"
+        s"${dottyLibRoot}/scala=compile",
       )))
       .add(SiteRoot("docs"))
       .add(ApiSubdirectory(true))

scaladoc-testcases/src/tests/snippetCompilerTests.scala

@@ -54,6 +54,24 @@ class A {
  */
 class B { }
 
+/**
+ * ```scala sc:macrocompile
+ *    inline def sum(args: Int*): Int = ${ sumExpr('args) }
+ *    def sumExpr(argsExpr: Expr[Seq[Int]])(using Quotes): Expr[Int] = argsExpr match
+ *      case Varargs(Exprs(args)) => ???
+ *        // args: Seq[Int]
+ * ```
+ */
+class C { }
+
+/**
+   * ```scala sc:usingquotes
+   *    import quotes.reflect.*
+   *    '{ List(${Varargs(List('{1}, '{2}, '{3}))}: _*) } // equivalent to '{ List(1, 2, 3) }
+   * ```
+   */
+class D { }
+
 trait Quotes {
   val reflect: reflectModule = ???
   trait reflectModule { self: reflect.type =>
@@ -65,4 +83,4 @@ trait Quotes {
       */
     def a = 3
   }
-}
+}

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetChecker.scala

@@ -44,18 +44,42 @@ class SnippetChecker(val args: Scaladoc.Args)(using cctx: CompilerContext):
     lineOffset: SnippetChecker.LineOffset,
     sourceFile: SourceFile
   ): Option[SnippetCompilationResult] = {
-    if arg.flag != SCFlags.NoCompile then
-      val wrapped = WrappedSnippet(
-        snippet,
-        data.map(_.packageName),
-        data.fold(Nil)(_.classInfos),
-        data.map(_.imports).getOrElse(Nil),
-        lineOffset + data.fold(0)(_.position.line) + constantLineOffset,
-        data.fold(0)(_.position.column) + constantColumnOffset
-      )
-      val res = compiler.compile(wrapped, arg, sourceFile)
-      Some(res)
-    else None
+    arg.flag match 
+      case SCFlags.Compile | SCFlags.Fail => 
+        val wrapped = WrappedSnippet(
+          snippet,
+          data.map(_.packageName),
+          data.fold(Nil)(_.classInfos),
+          data.map(_.imports).getOrElse(Nil),
+          lineOffset + data.fold(0)(_.position.line) + constantLineOffset,
+          data.fold(0)(_.position.column) + constantColumnOffset
+        )
+        val res = compiler.compile(wrapped, arg, sourceFile)
+        Some(res)
+      case SCFlags.MacroCompile =>
+        val wrapped = WrappedSnippet(
+          snippet, 
+          data.map(_.packageName),
+          data.map(_.imports).getOrElse(Nil),
+          lineOffset + data.fold(0)(_.position.line) + constantLineOffset,
+          data.fold(0)(_.position.column) + constantColumnOffset
+        )
+        val res = compiler.compile(wrapped, arg, sourceFile)
+        Some(res)
+      case SCFlags.UsingQuotes =>
+        val wrapped = WrappedSnippet(
+          snippet,
+          data.map(_.packageName),
+          data.fold(Nil)(_.classInfos),
+          data.map(_.imports).getOrElse(Nil),
+          lineOffset + data.fold(0)(_.position.line) + constantLineOffset,
+          data.fold(0)(_.position.column) + constantColumnOffset,
+          true
+        )
+        val res = compiler.compile(wrapped, arg, sourceFile)
+        Some(res)
+      case SCFlags.NoCompile => None
+
   }
 
 object SnippetChecker:

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetCompilerArgs.scala

@@ -6,14 +6,12 @@ import java.nio.file.Path
 case class SnippetCompilerArg(flag: SCFlags):
   def overrideFlag(f: SCFlags): SnippetCompilerArg = copy(flag = f)
 
-sealed trait SCFlags(val flagName: String)
-
-object SCFlags:
-  case object Compile extends SCFlags("compile")
-  case object NoCompile extends SCFlags("nocompile")
-  case object Fail extends SCFlags("fail")
-
-  def values: Seq[SCFlags] = Seq(Compile, NoCompile, Fail)
+enum SCFlags(val flagName: String):
+  case Compile extends SCFlags("compile")
+  case MacroCompile extends SCFlags("macrocompile")
+  case UsingQuotes extends SCFlags("usingquotes")
+  case NoCompile extends SCFlags("nocompile")
+  case Fail extends SCFlags("fail")
 
 case class SnippetCompilerArgs(scFlags: PathBased[SCFlags], defaultFlag: SCFlags):
   def get(member: Member): SnippetCompilerArg =
@@ -41,6 +39,8 @@ object SnippetCompilerArgs:
     |
     |Available flags:
     |compile - Enables snippet checking.
+    |macrocompile - Enables snippet checking for macros. 
+    |usingquotes - Enables checking snippet additionally wrapped in `scala.quoted.Quotes` impilicit scope.
     |nocompile - Disables snippet checking.
     |fail - Enables snippet checking, asserts that snippet doesn't compile.
     |

scaladoc/src/dotty/tools/scaladoc/snippets/WrappedSnippet.scala

@@ -10,50 +10,52 @@ object WrappedSnippet:
 
   val indent: Int = 2
 
-  def apply(str: String): WrappedSnippet =
-    val baos = new ByteArrayOutputStream()
-    val ps = new PrintStream(baos)
-    ps.startHide()
-    ps.println("package snippets")
-    ps.println("object Snippet {")
-    ps.endHide()
-    str.split('\n').foreach(ps.printlnWithIndent(indent, _))
-    ps.startHide()
-    ps.println("}")
-    ps.endHide()
-    WrappedSnippet(baos.toString, 0, 0, indent + 2 /*Hide tokens*/, indent)
+  def apply(
+    str: String,
+    packageName: Option[String],
+    imports: List[String],
+    outerLineOffset: Int,
+    outerColumnOffset: Int
+  ): WrappedSnippet =
+    apply(str, packageName, Nil, imports, outerLineOffset, outerColumnOffset)
 
   def apply(
     str: String,
     packageName: Option[String],
     classInfos: Seq[SnippetCompilerData.ClassInfo],
     imports: List[String],
     outerLineOffset: Int,
-    outerColumnOffset: Int
+    outerColumnOffset: Int,
+    usingQuotes: Boolean = false
   ): WrappedSnippet =
     val baos = new ByteArrayOutputStream()
     val ps = new PrintStream(baos)
     ps.startHide()
     ps.println(s"package ${packageName.getOrElse("snippets")}")
     imports.foreach(i => ps.println(s"import $i"))
-    val notEmptyClassInfos = if classInfos.isEmpty then Seq(SnippetCompilerData.ClassInfo(None, Nil, None)) else classInfos
-    notEmptyClassInfos.zipWithIndex.foreach { (info, i) =>
-      ps.printlnWithIndent(indent * i, s"trait Snippet$i${info.generics.getOrElse("")} { ${info.tpe.fold("")(cn => s"self: $cn =>")}")
-      info.names.foreach{ name =>
-        ps.printlnWithIndent(indent * i + indent, s"val $name = self")
+    val classInfoSize = if classInfos.isEmpty then 1 else classInfos.length + (if usingQuotes then 1 else 0)
+    if classInfos.isEmpty then 
+      ps.println("object Snippet {")
+    else
+      classInfos.zipWithIndex.foreach { (info, i) =>
+        ps.printlnWithIndent(indent * i, s"trait Snippet$i${info.generics.getOrElse("")} { ${info.tpe.fold("")(cn => s"self: $cn =>")}")
+        info.names.foreach{ name =>
+          ps.printlnWithIndent(indent * i + indent, s"val $name = self")
+        }
       }
-    }
+    if usingQuotes then 
+      ps.printlnWithIndent(classInfos.length * indent, "def f(using Quotes) = {")
     ps.endHide()
-    str.split('\n').foreach(ps.printlnWithIndent(notEmptyClassInfos.size * indent, _))
+    str.split('\n').foreach(ps.printlnWithIndent(classInfoSize * indent, _))
     ps.startHide()
-    (0 to notEmptyClassInfos.size -1).reverse.foreach( i => ps.printlnWithIndent(i * indent, "}"))
+    (0 to classInfoSize -1).reverse.foreach( i => ps.printlnWithIndent(i * indent, "}"))
     ps.endHide()
     WrappedSnippet(
       baos.toString,
       outerLineOffset,
       outerColumnOffset,
-      notEmptyClassInfos.size + notEmptyClassInfos.flatMap(_.names).size + packageName.size + 2 /*Hide tokens*/,
-      notEmptyClassInfos.size * indent
+      classInfoSize + classInfos.flatMap(_.names).size + packageName.size + 2 /*Hide tokens*/,
+      classInfoSize * indent
     )
 
   extension (ps: PrintStream)