Add arguments to control snippet compiler.

Author: pikinier20

project/Build.scala

@@ -1614,6 +1614,11 @@ object Build {
           val stdLibRoot = projectRoot.relativize(managedSources.toPath.normalize())
           val docRootFile = stdLibRoot.resolve("rootdoc.txt")
 
+          val dottyManagedSources =
+            (`stdlib-bootstrapped`/Compile/sourceManaged).value / "dotty-library-src"
+
+          val dottyLibRoot = projectRoot.relativize(dottyManagedSources.toPath.normalize())
+
           if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
           else Def.task{
             IO.write(dest / "versions" / "latest-nightly-base", majorVersion)
@@ -1644,6 +1649,9 @@ object Build {
                 s"$stdLibRoot=github://scala/scala/v${stdlibVersion(Bootstrapped)}#src/library," +
                 s"docs=github://lampepfl/dotty/master#docs",
               "-doc-root-content", docRootFile.toString,
+              "-snippet-compiler-args:" +
+                s"$dottyLibRoot/scala/quoted=nocompile," +
+                s"$dottyLibRoot=compile",
               "-Ydocument-synthetic-types"
             )
           ))

scaladoc-testcases/src/tests/snippetCompilerTest.scala

@@ -0,0 +1,14 @@
+package snippetCompiler
+
+/**
+  * ```scala sc:compile
+  * def a = 2
+  * a
+  * ```
+  *
+  * ```scala sc:nocompile
+  * def a = 3
+  * a()
+  * ```
+  */
+class A { }

scaladoc/src/dotty/tools/scaladoc/DocContext.scala

@@ -70,6 +70,9 @@ case class NavigationNode(name: String, dri: DRI, nested: Seq[NavigationNode])
 
 case class DocContext(args: Scaladoc.Args, compilerContext: CompilerContext):
   lazy val sourceLinks = SourceLinks.load(args.sourceLinks, args.revision)(using compilerContext)
+
+  lazy val snippetCompilerArgs = snippets.SnippetCompilerArgs.load(args.snippetCompilerArgs)(using compilerContext)
+
   lazy val staticSiteContext = args.docsRoot.map(path => StaticSiteContext(
       File(path).getAbsoluteFile(),
       args,

scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala

@@ -44,6 +44,7 @@ object Scaladoc:
     regexesToSkip: List[String] = Nil,
     rootDocPath: Option[String] = None,
     documentSyntheticTypes: Boolean = false,
+    snippetCompilerArgs: List[String] = Nil
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -60,7 +61,7 @@ object Scaladoc:
       val tastyFiles = parsedArgs.tastyFiles ++ parsedArgs.tastyDirs.flatMap(listTastyFiles)
 
       if !ctx.reporter.hasErrors then
-        val updatedArgs = parsedArgs.copy(tastyDirs = Nil, tastyFiles = tastyFiles)
+        val updatedArgs = parsedArgs.copy(tastyDirs = parsedArgs.tastyDirs, tastyFiles = tastyFiles)
 
         if (parsedArgs.output.exists()) util.IO.delete(parsedArgs.output)
 
@@ -173,7 +174,8 @@ object Scaladoc:
         skipById.get ++ deprecatedSkipPackages.get,
         skipByRegex.get,
         docRootContent.nonDefault,
-        YdocumentSyntheticTypes.get
+        YdocumentSyntheticTypes.get,
+        snippetCompilerArgs.get
       )
       (Some(docArgs), newContext)
     }

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

@@ -60,5 +60,8 @@ class ScaladocSettings extends SettingGroup with CommonScalaSettings:
   val YdocumentSyntheticTypes: Setting[Boolean] =
     BooleanSetting("-Ydocument-synthetic-types", "Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib", false)
 
+  val snippetCompilerArgs: Setting[List[String]] =
+    MultiStringSetting("-snippet-compiler-args", "snippet-compiler-args", snippets.SnippetCompilerArgs.usage)
+
   def scaladocSpecificSettings: Set[Setting[_]] =
-    Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent)
+    Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompilerArgs)

scaladoc/src/dotty/tools/scaladoc/api.scala

@@ -234,4 +234,9 @@ extension (s: Signature)
 
 case class TastyMemberSource(val path: java.nio.file.Path, val lineNumber: Int)
 
-case class SnippetCompilerData(val packageName: String, val classType: Option[String], val classGenerics: Option[String], val imports: List[String])
+case class SnippetCompilerData(
+  val packageName: String,
+  val classType: Option[String],
+  val classGenerics: Option[String],
+  val imports: List[String]
+)

scaladoc/src/dotty/tools/scaladoc/renderers/WikiDocRenderer.scala

@@ -8,16 +8,21 @@ import dotty.tools.scaladoc.tasty.comments.wiki.WikiDocElement
 import dotty.tools.scaladoc.tasty.comments.markdown.DocFlexmarkRenderer
 import dotty.tools.scaladoc.snippets._
 
-class DocRender(signatureRenderer: SignatureRenderer, snippetChecker: SnippetChecker)(using DocContext):
+class DocRender(signatureRenderer: SignatureRenderer, snippetChecker: SnippetChecker)(using ctx: DocContext):
 
-  private val snippetCheckingFunc: Member => String => Unit =
+  private val snippetCheckingFunc: Member => (String, Option[SnippetCompilerArg]) => Unit =
   (m: Member) => {
-    (str: String) => {
-        snippetChecker.checkSnippet(str, m.docs.map(_.snippetCompilerData)) match {
-          case r @ SnippetCompilationResult(None, _) =>
-            println(s"In member ${m.name}:")
-            println(r.getSummary)
-          case _ =>
+    (str: String, argOverride: Option[SnippetCompilerArg]) => {
+        val arg = argOverride.fold(
+          ctx.snippetCompilerArgs.get(m).fold(SnippetCompilerArg.default)(p => p)
+        )(p => p)
+
+        snippetChecker.checkSnippet(str, m.docs.map(_.snippetCompilerData), arg).foreach { _ match {
+            case r @ SnippetCompilationResult(None, _) =>
+              println(s"In member ${m.name} (${m.dri.location}):")
+              println(r.getSummary)
+            case _ =>
+          }
         }
     }
   }
@@ -62,7 +67,7 @@ class DocRender(signatureRenderer: SignatureRenderer, snippetChecker: SnippetChe
           case 6 => h6(content)
     case Paragraph(text) => p(renderElement(text))
     case Code(data: String) =>
-      snippetCheckingFunc(m)(data)
+      snippetCheckingFunc(m)(data, None)
       pre(code(raw(data))) // TODO add classes
     case HorizontalRule => hr
 

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

@@ -2,26 +2,36 @@ package dotty.tools.scaladoc
 package snippets
 
 import dotty.tools.scaladoc.DocContext
+import java.nio.file.Paths
 
-class SnippetChecker(
-  private val compiler: SnippetCompiler = SnippetCompiler(),
+class SnippetChecker()(using ctx: DocContext):
+  private val sep = System.getProperty("path.separator")
+  private val cp = System.getProperty("java.class.path") + sep +
+      Paths.get(ctx.args.classpath).toAbsolutePath + sep +
+      ctx.args.tastyDirs.map(_.getAbsolutePath()).mkString(sep)
+  private val compiler: SnippetCompiler = SnippetCompiler(classpath = cp)
   private val wrapper: SnippetWrapper = SnippetWrapper()
-):
   var warningsCount = 0
   var errorsCount = 0
 
-  def checkSnippet(snippet: String, data: Option[SnippetCompilerData]): SnippetCompilationResult = {
-    val wrapped = wrapper.wrap(
-      snippet,
-      data.map(_.packageName),
-      data.flatMap(_.classType),
-      data.flatMap(_.classGenerics),
-      data.map(_.imports).getOrElse(Nil)
-    )
-    val res = compiler.compile(wrapped)
-    if !res.messages.filter(_.level == MessageLevel.Error).isEmpty then errorsCount = errorsCount + 1
-    if !res.messages.filter(_.level == MessageLevel.Warning).isEmpty then warningsCount = warningsCount + 1
-    res
+  def checkSnippet(
+    snippet: String,
+    data: Option[SnippetCompilerData],
+    arg: SnippetCompilerArg
+  ): Option[SnippetCompilationResult] = {
+    if arg.is(SCFlags.Compile) then
+      val wrapped = wrapper.wrap(
+        snippet,
+        data.map(_.packageName),
+        data.flatMap(_.classType),
+        data.flatMap(_.classGenerics),
+        data.map(_.imports).getOrElse(Nil)
+      )
+      val res = compiler.compile(wrapped)
+      if !res.messages.filter(_.level == MessageLevel.Error).isEmpty then errorsCount = errorsCount + 1
+      if !res.messages.filter(_.level == MessageLevel.Warning).isEmpty then warningsCount = warningsCount + 1
+      Some(res)
+    else None
   }
 
   def summary: String = s"""

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

@@ -0,0 +1,80 @@
+package dotty.tools.scaladoc
+package snippets
+
+case class SnippetCompilerArg(flags: Set[SCFlags]):
+  def is(flag: SCFlags): Boolean = flags.contains(flag)
+
+object SnippetCompilerArg:
+  def default: SnippetCompilerArg = SnippetCompilerArg(
+    Set(SCFlags.NoCompile)
+  )
+
+enum SCFlags(val flagName: String, val forbiddenFlags: Set[SCFlags]):
+  case Compile extends SCFlags("compile", Set())
+  case NoCompile extends SCFlags("nocompile", Set())
+
+case class SnippetCompilerArgs(scArgs: PathBased[SnippetCompilerArg]):
+  def get(member: Member): Option[SnippetCompilerArg] = member.sources.flatMap(s => scArgs.get(s.path).map(_.elem))
+
+object SnippetCompilerArgs:
+  val usage =
+    """
+    |Snippet compiler arguments provide a way to configure snippet checking.
+    |
+    |This setting accept list of arguments in format:
+    |arg := [path=]flag{&flag}
+    |where path is a prefix of source paths to members to which argument should be set.
+    |
+    |If path is not present, argument will be used as default.
+    |
+    |Available flags:
+    |compile - Enables snippet checking. Cannot be used with nocompile.
+    |nocompile - Disables snippet checking. Cannot be used with compile.
+    |
+    """.stripMargin
+
+  def load(args: List[String])(using CompilerContext): SnippetCompilerArgs = {
+    PathBased.parse[SnippetCompilerArg](args)(using SnippetCompilerArgParser) match {
+      case PathBased.ParsingResult(errors, res) =>
+        if errors.nonEmpty then report.warning(
+          s"""Got following errors during snippet compiler args parsing:
+            |$errors
+            |
+            |${usage}
+            |""".stripMargin
+        )
+        SnippetCompilerArgs(res)
+    }
+  }
+
+object SnippetCompilerArgParser extends ArgParser[SnippetCompilerArg]:
+  def parse(s: String): Either[String, SnippetCompilerArg] = {
+    val flagStrings = s.split("&")
+    val (parsed, errors) = flagStrings.map(flag => SCFlags.values.find(_.flagName == flag).fold(
+        Left(s"$flag: No such flag found.")
+      )(
+        Right(_)
+      )
+    ).partition(_.isRight)
+
+    val (flags, errors2) = parsed.collect {
+      case Right(flag) => flag
+    } match {
+      case list => list.map(f =>
+        list.find(elem => f.forbiddenFlags.contains(elem)) match {
+          case Some(forbiddenElem) => Left(s"${f.flagName}: Cannot be used with flag: ${forbiddenElem.flagName}")
+          case None => Right(f)
+        }
+      ).partition(_.isRight)
+    }
+
+    val checkedFlags = flags.collect {
+      case Right(flag) => flag
+    }.toSet
+
+    val allErrors = (errors ++ errors2).collect {
+      case Left(error) => error
+    }.toList
+
+    if !allErrors.isEmpty then Left(allErrors.mkString("\n")) else Right(SnippetCompilerArg(checkedFlags))
+  }

scaladoc/src/dotty/tools/scaladoc/tasty/comments/markdown/DocFlexmarkExtension.scala

@@ -45,19 +45,21 @@ object DocFlexmarkParser {
     }
 }
 
-case class DocFlexmarkRenderer(renderLink: (DocLink, String) => String, snippetCheckingFunc: (String) => Unit)
+case class DocFlexmarkRenderer(renderLink: (DocLink, String) => String, snippetCheckingFunc: (String, Option[snippets.SnippetCompilerArg]) => Unit)
   extends HtmlRenderer.HtmlRendererExtension:
 
     def rendererOptions(opt: MutableDataHolder): Unit = () // noop
 
-    object CodeHandler extends CustomNodeRenderer[ast.Code]:
-      override def render(node: ast.Code, c: NodeRendererContext, html: HtmlWriter): Unit =
-        snippetCheckingFunc(node.getText.toString)
-        c.delegateRender()
-
-    object CodeBlockHandler extends CustomNodeRenderer[ast.CodeBlock]:
-      override def render(node: ast.CodeBlock, c: NodeRendererContext, html: HtmlWriter): Unit =
-        snippetCheckingFunc(node.getContentChars.toString)
+    object FencedCodeBlockHandler extends CustomNodeRenderer[ast.FencedCodeBlock]:
+      override def render(node: ast.FencedCodeBlock, c: NodeRendererContext, html: HtmlWriter): Unit =
+        val info = node.getInfo.toString
+        val argOverride =
+          info.split(" ")
+            .find(_.startsWith("sc:"))
+            .map(_.stripPrefix("sc:"))
+            .map(snippets.SnippetCompilerArgParser.parse)
+            .flatMap(_.toOption)
+        snippetCheckingFunc(node.getContentChars.toString, argOverride)
         c.delegateRender()
 
     object Handler extends CustomNodeRenderer[DocLinkNode]:
@@ -68,8 +70,7 @@ case class DocFlexmarkRenderer(renderLink: (DocLink, String) => String, snippetC
       override def getNodeRenderingHandlers: JSet[NodeRenderingHandler[_]] =
         JSet(
           new NodeRenderingHandler(classOf[DocLinkNode], Handler),
-          new NodeRenderingHandler(classOf[ast.Code], CodeHandler),
-          new NodeRenderingHandler(classOf[ast.CodeBlock], CodeBlockHandler)
+          new NodeRenderingHandler(classOf[ast.FencedCodeBlock], FencedCodeBlockHandler)
         )
 
     object Factory extends NodeRendererFactory:
@@ -79,6 +80,6 @@ case class DocFlexmarkRenderer(renderLink: (DocLink, String) => String, snippetC
       htmlRendererBuilder.nodeRendererFactory(Factory)
 
 object DocFlexmarkRenderer:
-  def render(node: Node)(renderLink: (DocLink, String) => String, snippetCheckingFunc: (String) => Unit) =
+  def render(node: Node)(renderLink: (DocLink, String) => String, snippetCheckingFunc: (String, Option[snippets.SnippetCompilerArg]) => Unit) =
     val opts = MarkdownParser.mkMarkdownOptions(Seq(DocFlexmarkRenderer(renderLink, snippetCheckingFunc)))
     HtmlRenderer.builder(opts).build().render(node)